claudlet 0.2.0

A pixel desktop buddy that reacts to Claude Code in real time

claudlet 🐾

English | 한국어

A tiny pixel creature that lives on your desktop and reacts to Claude Code in real time — it types while Claude works, waits when Claude needs you, celebrates when it's done, and roams around while you code. Click it to bring the terminal back to the front.

Drawn entirely in code — no image assets — so it's self-contained and original (CC0 artwork).

See it in action

Real desktop capture. Pets perch on the terminal titlebar, roam the desktop, doze off (💤) between tasks, and clamber over whatever else is on screen.

Perching on the terminal, roaming, and dozing between tasks.

Grab and drag them around; the rest keep roaming and napping.

They wander over whatever else is on your screen.

Install

Install with pipx (an isolated app install — pulls the deps, incl. pyobjc-framework-Quartz on macOS, and puts the claudlet* commands on your PATH), then wire it into Claude Code:

pipx install claudlet
claudlet-install      # registers the hooks + /claudlet skill (idempotent)

Check your version with claudlet-version (installed vs latest release). Update to the newest release with pipx upgrade claudlet && claudlet-install, or to the tip of develop (edge) with pipx install --force "git+https://github.com/YeeDochi/Claudlet@develop" && claudlet-install. Either way, restart your Claude Code session afterward (claude --continue) so the new hooks + pet code load. Or just run /claudlet update (release) / /claudlet update latest (master) from inside Claude Code and follow the prompts.

Remove it with claudlet-uninstall (stops pets, unregisters the hooks + skill; add --purge to also delete your config), then pipx uninstall claudlet.

Without pipx — one-line source install

Clones (or updates) to ~/claudlet, installs deps, registers hooks + skill:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/YeeDochi/Claudlet/master/install.py | python3 -

# Windows (PowerShell)
irm https://raw.githubusercontent.com/YeeDochi/Claudlet/master/install.py | python -

New Claude Code sessions then auto-spawn a pet. Restart any already-running session to pick up the hooks — or launch one now with claudlet.

Best on KDE Plasma. Perching on and riding windows also works on Windows (Win32) and macOS (experimental — needs pyobjc-framework-Quartz, which the installer adds automatically; the pet self-calibrates window coordinates at runtime). Elsewhere the window tricks switch off gracefully and the pet just roams. See Platform support.

What it shows

The creature's pose tracks what Claude is doing — editing, reading, calling MCP, spawning subagents, thinking, waiting on your input, celebrating (see the sheet above). In auto / bypass mode it puts on a VR visor and cruises, with a per-tool variant for each activity. It also perches on and rides your windows — walking along the top or living inside — and clips/hides when the window it's on is covered or minimized.

Commands

pipx install claudlet puts these on your PATH:

Command	What it does
claudlet	Launch a pet right now (standalone).
claudlet-install	Register the hooks + /claudlet skill in Claude Code — run once after installing.
claudlet-uninstall	Stop pets, unregister the hooks + skill, clean up (--purge also deletes your config).
claudlet-config	Show / scaffold / open the user config (--path, init, open).
claudlet-version	Show the installed version vs the latest PyPI release.
claudlet-attach	Attach a pet to the current Claude Code session.
claudlet-motion <name>	Play a motion on running pets (jump, wave, … ; stop, list).
claudlet-install-hooks	Just the hooks half of claudlet-install (--remove to undo).
claudlet-macos-diag	Print raw macOS window coordinates (perch troubleshooting).
claudlet-hook	Internal — invoked by Claude Code's hooks, not by you.

The /claudlet skill

claudlet-install also links a /claudlet skill into Claude Code, so you can drive the pet straight from a prompt:

• /claudlet — attach a pet to this session (so it reacts to the session's activity)
• /claudlet standalone — an unattached, decorative pet
• /claudlet <motion> — jump · wave · sing · juggle · float · celebrate · thinking · sleeping · error · attention (plus list, stop)
• /claudlet config — show the config, or just ask in plain language ("jump when I run Bash") and Claude edits it for you
• /claudlet update — update to the latest release (update latest for the tip of develop); shows your version and walks you through it

Docs

• Usage & interaction — drag & throw, click-to-focus, tray menu, motions, autostart, uninstall
• Configuration — remap which animation shows for which Claude Code activity (run claudlet-config or /claudlet config to locate & inspect it)
• Platform support — support matrix + how to test on your OS

License

Code: MIT (see LICENSE). Creature artwork: CC0 (see NOTICE).