clawface – OpenClaw Skill

---

name: clawface description: Floating avatar widget for AI agents showing emotions, actions, and visual effects. Give your OpenClaw a face! Use when the user wants visual feedback, a floating status window, or to see agent emotions while it works. Triggers on "show avatar", "uruchom avatara", "pokaż avatara", "agent face", "visual feedback".

🤖 ClawFace

Give your OpenClaw a face!

---

Got a dedicated machine running OpenClaw with a monitor? Tired of staring at logs all day?

Give your agent a personality!

• 9 emotions — from happy to angry, thinking to proud
• 9 actions — coding, searching, reading, speaking...
• 15 visual effects — matrix rain, fire, confetti, radar scan...

That's 1,215 unique combinations + custom messages from your agent!

Perfect for:

• 💻 Laptop setups where you want to SEE your agent working
• 🖥️ Dedicated OpenClaw machines with a monitor
• 🎮 Making your AI assistant feel alive
• 📺 Impressing your friends/coworkers

⚠️ Note: Only tested on macOS. Should work on Windows/Linux but YMMV.

---

🚀 Quick Test (try it now!)

# 1. Check if you have Python + tkinter:
python3 -c "import tkinter; print('Ready!')"

Terminal 1 — Run ClawFace:

python3 SKILL_PATH/scripts/avatar.py --mode robot

Terminal 2 — Run Demo:

python3 SKILL_PATH/scripts/avatar.py --demo

Watch the avatar cycle through all emotions, actions, and effects automatically! 🎉

Manual control:

echo '{"emotion":"excited","action":"success","effect":"confetti","message":"It works!"}' > ~/.clawface/avatar_state.json

---

⚠️ Requirements

Python 3.10+ with tkinter:

# Check:
python3 -c "import tkinter; print('OK')"

# Install if missing:
# macOS:   brew install python-tk@3.14
# Ubuntu:  sudo apt install python3-tk
# Windows: reinstall Python, check "tcl/tk and IDLE" during install

---

📦 Full Installation

1. Install the auto-thinking hook (recommended):

cp -r SKILL_PATH/hooks/clawface-thinking ~/.openclaw/hooks/
openclaw hooks enable clawface-thinking

This makes the avatar show "thinking" automatically when a turn starts — no delay!

2. Launch the avatar:

nohup python3 SKILL_PATH/scripts/avatar.py --mode robot > /dev/null 2>&1 &

Note: Replace SKILL_PATH with actual path, e.g., /usr/local/lib/node_modules/openclaw/skills/clawface

---

🎯 Core Principle: BE DYNAMIC!

Don't set one state and forget it. Update the avatar continuously as you work:

User asks question
  → thinking/reading    (reading their message)
  → thinking/thinking   (analyzing)
  → happy/speaking      (formulating response)  
  → neutral/idle        (sent, waiting)

Every action you take should be reflected. The avatar is your LIVE status indicator.

---

🎭 State Reference

Emotions

Emotion	Use when...
neutral	Default, waiting
thinking	Processing, analyzing
happy	Things going well
excited	Big win, celebration
proud	Personal achievement
confused	Uncertain, unexpected
tired	Long task
sad	Failed despite trying
angry	Error, frustration

Actions

Action	Use when...
idle	Waiting for user
reading	Reading files/docs
thinking	Analyzing, planning
searching	Web search, grep
coding	Writing code
loading	Running commands
speaking	Sending response
success	Completed task
error	Something failed

Effects

Effect	Vibe
none	Clean, minimal
matrix	Techy, data flow
radar	Scanning, searching
brainwave	Deep thinking
typing	Writing
soundwave	Speaking
gear	Mechanical work
fire	Intense, productive
lightning	Fast, powerful
confetti	Celebration!
heart	Affection
glitch	Error, broken
sparkles	Magic
pulse	Active but calm
progressbar:XX	Progress (0-100)

---

⚡ Best Practices

🔴 MINIMUM FLOW FOR EVERY RESPONSE:

thinking  →  processing user input
speaking  →  sending your reply  
idle      →  done, waiting

This is mandatory. Every single reply should show this progression.

Tips:

1. Update BEFORE each action — set reading before you read
2. Update AFTER completion — show success/error, then idle
3. Match intensity — small task = subtle, big task = expressive
4. Always return to idle — when waiting for user

---

🔧 Technical Reference

State File

Write JSON to ~/.clawface/avatar_state.json:

{
  "emotion": "happy",
  "action": "coding",
  "effect": "fire",
  "message": "Building something awesome!"
}

Display Modes

🤖 Robot Mode (--mode robot) — default

• LED-style pixel eyes with animations
• Mechanical arms with claws
• Retro-futuristic cyberpunk vibe
• Best for: tech aesthetic, dedicated screens

😊 Face Mode (--mode face)

• Simplified cartoon face
• Expressive eyes and mouth
• Friendly, approachable look
• Best for: casual use, smaller windows

Switch modes with buttons in the UI or restart with different --mode.

Window Controls

• Drag to move
• Drag edges to resize
• F for fullscreen
• Q to quit

🤖 ClawFace

Give your AI agent a face!

A floating avatar widget for OpenClaw agents showing real-time emotions, actions, and visual effects.

---

✨ Features

• 9 emotions — neutral, happy, excited, thinking, confused, tired, angry, sad, proud
• 9 actions — idle, coding, searching, reading, loading, speaking, success, error, thinking
• 15+ visual effects — matrix rain, fire, confetti, radar scan, brainwave, and more

= 1,215 unique combinations + custom text messages!

Two Display Modes

🤖 Robot Mode	😊 Face Mode
LED-style pixel eyes	Simplified cartoon face
Mechanical arms with claws	Expressive eyes and mouth
Retro-futuristic cyberpunk	Friendly, approachable

---

🚀 Quick Start

# 1. Check requirements
python3 -c "import tkinter; print('Ready!')"

# 2. Clone the repo
git clone https://github.com/mkoslacz/clawface.git
cd clawface

Terminal 1 — Run ClawFace:

python3 scripts/avatar.py --mode robot

Terminal 2 — Run Demo:

python3 scripts/avatar.py --demo

Watch the avatar cycle through all emotions, actions, and effects automatically! 🎉

Manual control (without demo):

mkdir -p ~/.clawface
echo '{"emotion":"excited","action":"success","effect":"confetti","message":"Hello!"}' > ~/.clawface/avatar_state.json

---

📦 Installation as OpenClaw Skill

# Copy to skills directory
cp -r clawface /path/to/openclaw/skills/

# Install the auto-thinking hook (optional but recommended)
cp -r clawface/hooks/clawface-thinking ~/.openclaw/hooks/
openclaw hooks enable clawface-thinking

The hook makes ClawFace show "thinking" automatically when a turn starts — no more delay between "typing" indicator and avatar update!

---

🎮 Usage

Control via State File

Write JSON to ~/.clawface/avatar_state.json:

{
  "emotion": "happy",
  "action": "coding",
  "effect": "fire",
  "message": "Building something awesome!"
}

From Shell

# Happy coding with fire effect
echo '{"emotion":"happy","action":"coding","effect":"fire","message":"On fire!"}' > ~/.clawface/avatar_state.json

# Thinking with brainwave
echo '{"emotion":"thinking","action":"thinking","effect":"brainwave","message":"Hmm..."}' > ~/.clawface/avatar_state.json

# Success with confetti!
echo '{"emotion":"excited","action":"success","effect":"confetti","message":"Done!"}' > ~/.clawface/avatar_state.json

From Python

import json
from pathlib import Path

def set_clawface(emotion="neutral", action="idle", effect="none", message=""):
    state = {"emotion": emotion, "action": action, "effect": effect, "message": message}
    state_file = Path.home() / ".clawface" / "avatar_state.json"
    state_file.parent.mkdir(exist_ok=True)
    state_file.write_text(json.dumps(state))

# Examples
set_clawface("thinking", "reading", "matrix", "Reading files...")
set_clawface("happy", "coding", "fire", "Writing code!")
set_clawface("excited", "success", "confetti", "Done!")

---

🎭 State Reference

Emotions

Emotion	Color	Use when...
neutral	Gray	Default, waiting
thinking	Cyan	Processing, analyzing
happy	Green	Things going well
excited	Yellow	Big win, celebration
proud	Orange	Personal achievement
confused	Pink	Uncertain, unexpected
tired	Dark blue	Long task
sad	Blue	Failed despite trying
angry	Red	Error, frustration

Actions

Action	Label	Use when...
idle	STANDBY	Waiting for user
reading	READING	Reading files/docs
thinking	THINKING	Analyzing, planning
searching	SEARCHING	Web search, grep
coding	CODING	Writing code
loading	LOADING	Running commands
speaking	OUTPUT	Sending response
success	SUCCESS!	Completed task
error	ERROR!	Something failed

Effects

Effect	Description
none	Clean, minimal
matrix	Falling code characters
radar	Scanning sweep
brainwave	Pulsing brain activity
typing	Typing animation
soundwave	Audio waveform
gear	Spinning gears
fire	Flames
lightning	Electric bolts
confetti	Celebration particles
heart	Floating hearts
glitch	Glitch effect
sparkles	Magic sparkles
pulse	Pulsing outline
progressbar:XX	Progress bar (0-100)

---

⚙️ Requirements

• Python 3.10+
• tkinter

# Check if tkinter is available
python3 -c "import tkinter; print('OK')"

# Install if missing:
# macOS
brew install python-tk@3.14

# Ubuntu/Debian
sudo apt install python3-tk

# Windows
# Reinstall Python, check "tcl/tk and IDLE" during install

---

🖥️ Window Controls

• Move: Drag the window
• Resize: Drag edges/corners
• Fullscreen: Press F or double-click
• Exit fullscreen: Press Escape
• Quit: Press Q
• Switch mode: Click Robot/Face buttons

---

🔗 Links

• OpenClaw: github.com/openclaw/openclaw
• ClawHub: clawhub.ai

---

📄 License

MIT

---

Made with 🦞 for the OpenClaw community