claudlet 0.3.2

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.

Real desktop capture — they wander over whatever else is on your screen.

Agent companions

When Claude spawns subagents, a little hard-hatted sidekick trails your pet for each one — a duckling chain that follows it around, mirrors what the subagent is doing, and waves goodbye when its agent finishes.

Real desktop capture — two subagents, two hatted companions trailing the session's pet.

Each companion wears a random hat so you can tell them apart:

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.

To uninstall, order matters — unhook first, then remove the package. claudlet-uninstall is the only step that removes the hooks from ~/.claude/settings.json; if you delete the package first, those hooks linger and Claude Code keeps trying to run a claudlet-hook that no longer exists.

claudlet-uninstall        # stops pets, unregisters the hooks + /claudlet skill
                          #   (add --purge to also delete your config)
pipx uninstall claudlet   # only after the line above succeeds

If claudlet-uninstall isn't found, or you installed from source

Command not found (common on Windows). The claudlet* commands live in pipx's bin directory; if it isn't on your PATH the shell can't find them. The fix:

pipx ensurepath        # add pipx's bin dir to PATH

Then restart your terminal and run claudlet-uninstall again. (pipx list prints the exact install location if you'd rather run the script by full path.)

Source install (the install.py one-liner clones to ~/claudlet — there's no pip package to remove). Run the checkout's own script, then delete the folder:

python ~/claudlet/bin/claudlet-uninstall
rm -rf ~/claudlet                                   # Windows: rmdir /s "%USERPROFILE%\claudlet"

Already removed the package without unhooking? The hook entries are still in ~/.claude/settings.json. Reinstall just long enough to unhook cleanly:

pipx install claudlet && claudlet-uninstall && pipx uninstall claudlet

or open ~/.claude/settings.json and delete the claudlet-hook entries by hand.

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 -

Unlike pipx, this does not put the claudlet* commands on your PATH — they live in ~/claudlet/bin. The hooks still work (Claude Code calls them by full path), but to run claudlet, claudlet-config, /claudlet update, etc. yourself, add that dir to your PATH:

# Linux / macOS — add to ~/.bashrc or ~/.zshrc, then restart the shell
export PATH="$HOME/claudlet/bin:$PATH"

# Windows (PowerShell) — persist for your user, then restart the terminal
setx PATH "$env:USERPROFILE\claudlet\bin;$env:PATH"

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, 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.

When Claude runs subagents, a hatted companion appears for each one (up to three) and trails the pet in a duckling chain, mirroring the subagent's activity and leaving with a little celebration when it finishes — so you can see agent work happening at a glance.

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
• Contributing — dev setup, running tests, code style, branch model
• Changelog — what changed in each release (English + Korean)

License

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