clawd-buddy 0.1.11

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
New session begins (UserPromptSubmit hook, first prompt)	Greets with a soft wave, a smaller smile, and a pulsing cyan border
Assistant is thinking (between UserPromptSubmit and Stop)	Pupils sweep upward, three pulsing dots float above the head, gentle purple border
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

If multiple signals arrive in quick succession (e.g. a PermissionRequest while a celebrate is still animating), the buddy now queues them instead of dropping them — up to three pending reactions play back in the order they arrived.

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": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "clawd-buddy --prompt-start",
            "timeout": 5000
          }
        ]
      }
    ],
    "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 new entries into the existing hooks object.

--prompt-start does two things in one: a soft greeting on the first prompt of each Claude Code session (de-duplicated by session_id read from the hook's stdin payload), then enters the thinking animation that runs until Stop arrives. Wiring it is optional — without it, the buddy still celebrates and waves, just without the session-start and mid-response reactions.

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 --prompt-start   Signal start of a Claude Code prompt — greets
                             on the first prompt of a new session, then
                             enters the thinking animation. Reads
                             session_id from JSON on stdin when run as a
                             hook command.
clawd-buddy --session-id ID  Override the session id used by --prompt-start
                             (mostly useful for scripts / tests)
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 --version        Show version and exit
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/UserPromptSubmit ──> clawd-buddy --prompt-start ──> TCP:44556 ──> greet (if new session) + thinking
 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 (prompt submitted, response done, permission needed).
2. The clawd-buddy --send / --wave / --prompt-start 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. Incoming signals during an active animation are queued (FIFO, capped at three) so attention requests are never silently dropped.

Signal protocol

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

{"action": "celebrate"}

{"action": "wave"}

{"action": "prompt_start", "session_id": "abc-123"}

The prompt_start action is the wire-once handler for a Claude Code prompt: the running buddy greets when it sees a new session_id (or when none is supplied and there has been no recent activity) and starts the thinking animation either way.

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.
• Clawd Buddy vX.Y.Z — informational version label (disabled)
• About — open a small dialog with version, description, author, license, and a clickable repo link
• 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

Greet (first prompt of a new session)

• Medium bobbing
• Small happy arc eyes
• Smaller smile
• Right arm raised in a friendly hello
• Pulsing cyan border around the body
• Silent (audio is intentionally deferred to a later milestone)
• Duration: ~1.8 seconds
• Per-session de-duplication via Claude Code's session_id

Thinking (between UserPromptSubmit and Stop)

• Slow, calm bobbing
• Pupils sweep upward and side-to-side (a "considering" pose)
• Three small pulsing dots float above the head
• Soft purple border, gentler pulse than the other states
• Silent
• Holds indefinitely until Stop arrives (with a 10-minute safety cap in case the assistant crashes or the network drops)

Reactions are queued while another animation is playing — up to three pending events play back in the order they arrived.

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