clawd-buddy 0.1.9

Animated terminal pet that sits on your taskbar and reacts to AI coding assistant events

Clawd Buddy

A tiny animated terminal pet that sits on your taskbar and reacts to Claude Code events. Works on Windows and Linux.

What it does

Clawd Buddy is a small always-on-top character that lives on your taskbar while you work with Claude Code:

State	What happens
Idle	Gently bobs, blinks, breathes — your quiet companion
Assistant finishes (Stop hook)	Celebrates with confetti, happy eyes, waving arms, a short motivational fanfare, and a pulsing green border
Assistant needs permission (PermissionRequest hook)	Waves with a floating !, a warm two-note doorbell call, and a pulsing yellow border

Notification sound packs

Pick the audio style from the system-tray right-click menu → Sound. Four packs ship in the box, plus an Off entry to mute. Clicking a pack previews the celebrate sound immediately so you can audition options without waiting for the next event.

Pack	Celebrate	Wave
Fanfare (default)	Motivational ascending C-major arpeggio that lands on a full triad chord	Warm two-note doorbell (G4 → D4)
Chime	Two ascending bell tones with harmonic decay	Single lower bell
Retro	8-bit square-wave coin-pickup flourish (C5 → E5 → G5 → C6)	Two short low-high blips
Minimal	Single short soft pip	Single short low pip
Off	(silent)	(silent)

No audio file is bundled — every pack is synthesized at startup with pygame.mixer (summed sine / square / bell-decay voices with raised-cosine envelopes). Your choice persists across launches in config.json under "sound_pack".

Toggle from the system-tray right-click menu → Sound. The choice is remembered between launches (saved alongside the theme in config.json). If your machine has no audio device, the buddy logs a one-line warning and runs silently while the visual border still works.

Themes

Clawd Buddy ships with 8 color themes — a mix of dark and light with several popular palettes:

#	Theme	Flavor
1	dark	Classic dark blue-gray (default)
2	light	Classic soft light
3	dracula	Dark with purple / pink accents
4	monokai	Dark with green / pink accents
5	nord	Cool nordic blue
6	gruvbox	Warm retro dark
7	solarized	Muted solarized light
8	sunset	Warm peach / orange light

Pick one at launch:

clawd-buddy --theme dark        # default
clawd-buddy --theme dracula
clawd-buddy --theme sunset

Switch at runtime from the Theme submenu on the system-tray icon (right-click the clawd-buddy tray icon → Theme → pick one). The active theme is marked as a radio item.

Your choice is remembered between launches. The buddy stores the last theme in:

• Windows: %APPDATA%\clawd-buddy\config.json
• Linux: $XDG_CONFIG_HOME/clawd-buddy/config.json (falls back to ~/.config/clawd-buddy/config.json)

Passing --theme <name> at launch overrides and updates the remembered theme, so the override sticks for next time too. First-run default is dark.

Platform support

Platform	Transparency	Always-on-top	Autostart
Windows 10/11	Color-key (fully transparent background)	Win32 HWND_TOPMOST	VBS in Startup folder
Linux (X11)	Themed background (dark or light)	_NET_WM_STATE_ABOVE	.desktop in ~/.config/autostart/

Linux notes: Requires an X11 session (Wayland restricts window positioning and always-on-top). Most Wayland desktops support XWayland — set SDL_VIDEODRIVER=x11 (done automatically). Panel/dock height is auto-detected via _NET_WORKAREA; falls back to 48px.

Install

# With uv (recommended — installs as an isolated tool)
uv tool install clawd-buddy

# With pipx
pipx install clawd-buddy

# With pip (into current environment)
pip install clawd-buddy

From source

git clone https://github.com/ramymagdy-rm/clawd-buddy.git
cd clawd-buddy
uv tool install --from . clawd-buddy

Update

# With uv
uv tool install --upgrade clawd-buddy

# With pipx
pipx upgrade clawd-buddy

# With pip
pip install --upgrade clawd-buddy

Quick start

1. Launch the buddy

clawd-buddy

The buddy appears on your taskbar, centered at the bottom of the screen. It runs until you close it.

2. Run at startup (optional)

# Enable — buddy starts automatically at login
clawd-buddy --startup

# Disable — remove from startup
clawd-buddy --no-startup

• Windows: Places a VBS launcher in shell:startup. No console window appears.
• Linux: Creates a .desktop file in ~/.config/autostart/.

3. Wire up Claude Code hooks

Add to your global Claude Code settings (~/.claude/settings.json) so every session triggers the buddy:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "clawd-buddy --send done",
            "timeout": 5000
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "clawd-buddy --wave",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Note: If you already have other hooks in your settings.json, merge the Stop and PermissionRequest entries into the existing hooks object.

4. Done

Start a Claude Code session anywhere. When the assistant finishes or needs your attention, the buddy reacts.

CLI reference

clawd-buddy                  Start buddy on taskbar
clawd-buddy --test           Start with a celebration animation
clawd-buddy --send MSG       Signal a running buddy to celebrate
clawd-buddy --wave           Signal a running buddy to wave (needs attention)
clawd-buddy --top            Tell a running buddy to re-assert always-on-top
clawd-buddy --quit           Ask a running buddy to exit cleanly
clawd-buddy --theme THEME    Color theme: dark (default), light, dracula,
                             monokai, nord, gruvbox, solarized, sunset
clawd-buddy --startup        Enable run at login/startup
clawd-buddy --no-startup     Disable run at login/startup
clawd-buddy --port PORT      Use a custom TCP port (default: 44556)
clawd-buddy --no-topmost     Don't keep the window always-on-top
clawd-buddy --fg             Run in foreground (skip auto-detach)
clawd-buddy --help           Show help

Controls

Input	Action
Drag	Click anywhere on the buddy and drag to reposition
Space	Trigger a test celebration
Ctrl+1	Scale to 100% (default)
Ctrl+2	Scale to 125%
Ctrl+3	Scale to 150%
Ctrl+4	Scale to 200%
Escape	Quit the buddy
Tray icon	Right-click the system tray icon for a menu — theme switcher lives here

How it works

Architecture

Claude Code                            Clawd Buddy
-----------                            -----------
 hooks/Stop ──> clawd-buddy --send ──> TCP:44556 ──> celebrate animation
 hooks/PermissionRequest ──> clawd-buddy --wave ──> TCP:44556 ──> wave animation

1. Claude Code hooks fire shell commands when events happen (response done, permission needed).
2. The clawd-buddy --send / --wave CLI connects to 127.0.0.1:44556 and sends a JSON action.
3. The running buddy process receives the signal and plays the animation.

Signal protocol

The buddy listens on a TCP socket (default port 44556). Send a JSON payload to trigger actions:

{"action": "celebrate"}

{"action": "wave"}

You can send signals from any language:

import socket, json
s = socket.socket()
s.connect(("127.0.0.1", 44556))
s.sendall(json.dumps({"action": "celebrate"}).encode())
s.close()

echo '{"action": "wave"}' | nc localhost 44556

Single instance

Only one buddy can run at a time. If you launch clawd-buddy while one is already running, it sends a signal to the existing instance and exits.

System tray

The buddy adds a system tray icon with a right-click menu:

• Test Celebration — trigger the celebrate animation
• Bring to Front — re-assert always-on-top (recovers z-order)
• Theme — pick one of the 8 themes (current one is checked)
• Sound — pick a notification sound pack (Off, Fanfare, Chime, Retro, Minimal). Selecting a pack plays a preview immediately; the choice is persisted in config.json.
• Quit — close the buddy

Autostart

clawd-buddy --startup registers the buddy to launch at login. clawd-buddy --no-startup removes it.

• Windows: Places a VBS launcher in %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\. Starts with a hidden console window.
• Linux: Creates a .desktop file in ~/.config/autostart/. Uses the XDG autostart standard supported by GNOME, KDE, XFCE, and others.

Animations

Idle

• Gentle vertical bobbing (sine wave)
• Periodic blinking (every ~5 seconds)
• Pupils wander slowly
• Small mouth line with subtle movement
• Arms sway gently at sides

Celebrate (on Stop)

• Fast bouncing
• Happy arc eyes (^ ^)
• Wide smile
• Both arms waving up
• Legs kicking
• Confetti burst (40 particles with gravity and drag)
• Pulsing green border around the body
• Motivational C-major arpeggio + triad chord (if Sound is enabled)
• Duration: 3.5 seconds

Wave (on PermissionRequest)

• Medium bobbing
• Wide alert eyes (large pupils, staring)
• Surprised "o" mouth
• Right arm waving high
• Pulsing floating ! indicator above head
• Pulsing yellow border around the body
• Warm two-note doorbell call (if Sound is enabled)
• Duration: 5 seconds

Configuration

Custom port

If port 44556 is taken, use a different one:

clawd-buddy --port 55000

Update your hooks to match:

"command": "clawd-buddy --send done --port 55000"

Disable always-on-top

clawd-buddy --no-topmost

Troubleshooting

Buddy doesn't appear

• Windows: Make sure no other process is using port 44556: netstat -ano | findstr 44556
• Linux: Requires an X11 session. If you're on Wayland, the buddy forces SDL_VIDEODRIVER=x11 via XWayland. If it still doesn't appear, try clawd-buddy --fg to see errors in the terminal.
• macOS: Not yet supported.

Hook doesn't trigger the buddy

• Make sure the buddy is running (clawd-buddy in a terminal or via --startup).
• Test manually: clawd-buddy --send test — if this says "No buddy on port 44556", the buddy isn't running.
• Check that clawd-buddy is on your PATH: where clawd-buddy (Windows) / which clawd-buddy (Linux)

Multiple buddies / port conflict

• The buddy uses a lock socket on port 44557 (main port + 1) to prevent duplicates.
• Windows: taskkill /F /IM clawd-buddy.exe
• Linux: pkill -f clawd-buddy

Startup not working

Windows:

• Verify the VBS file exists: dir "%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\clawd-buddy*"
• Re-run clawd-buddy --startup to regenerate it.

Linux:

• Verify the desktop file exists: ls ~/.config/autostart/clawd-buddy.desktop
• Re-run clawd-buddy --startup to regenerate it.
• Make sure clawd-buddy is on your PATH: which clawd-buddy

Linux: window has a visible background

On Linux, color-key transparency is not available. The buddy renders on a themed background that matches whichever of the 8 themes you choose. Pick a light theme (light, solarized, sunset) on light panels/docks, or a dark one (dark, dracula, monokai, nord, gruvbox) on dark ones to blend in.

Disclaimer

Clawd Buddy is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic, PBC.

License

MIT