claudlet 🐾

English | 한국어

A tiny pixel creature that lives on your desktop and reacts to Claude Code (and Codex) in real time — it types while the agent works, waits when it 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).

Real desktop capture — perching on titlebars, dozing off between tasks, climbing over whatever's on screen.

Install

pipx install claudlet
claudlet-install      # hooks + /claudlet skill, for every agent found (Claude Code, Codex)

New sessions then spawn a pet on their own; restart sessions that were already running. Best on KDE Plasma; perching on windows also works on Windows and macOS, and elsewhere the pet just roams. See Platform support.

[features]
hooks = true

claudlet-version                                                                           # installed vs latest
pipx upgrade claudlet && claudlet-install                                                  # latest release
pipx install --force "git+https://github.com/YeeDochi/Claudlet@develop" && claudlet-install # tip of develop

claudlet-uninstall        # stops pets, unregisters hooks + skill (--purge: config too)
pipx uninstall claudlet   # only after the line above succeeds

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

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

What it shows

The pose tracks what the agent is doing — editing, reading, calling MCP, thinking, waiting on you, done, failed. Running unattended (auto / bypass mode) pulls a VR visor over its eyes.

When the agent spawns subagents, a hatted companion trails the pet for each one (up to three), mirrors what it's doing, and waves goodbye when it finishes.

Talking to it

Right-click → 💬 Start a conversation… opens a chat window. Enter types your line straight into the session; right-click ➤ → 📝 Leave as a note has the pet hold it in its mouth until the next tool call or prompt. 🎯 lets you drag over a window so what's on it rides along with your next line.

The answer comes back in the creature's own voice, in a bubble over its head — each creature can have its own name and voice (settings page).

Turn on Creature answers first (settings → preferences) and what you say goes to the creature instead of your session: a separate, hook-free one-shot call that reads the session's recent activity, answers small talk itself, and hands real work to the session — so chatting never interrupts the agent mid-task. Each message is its own call, so it's off by default.

Fetching a window

Lost a window behind ten others, or minimized it? Ask the agent — "bring up the Slack window" — and the pet goes and gets it, the app's icon in its mouth. A minimized window rises up right where the pet stood; a buried one gets tugged back in steps.

KDE Plasma and Windows. On macOS minimized windows aren't listed and it fronts the whole app.

Make it yours

/claudlet setting (or claudlet-config ui) opens a page to pick which creature the pet wears and its colour and size, previewed with the real renderer. With more than one agent installed, each gets its own tab.

Four creatures ship with the pet, and /claudlet make <what you want> writes a new one (/claudlet make a grumpy little robot):

A creature is a small Python package, so it can be drawn with rectangles, blitted from a sprite sheet, anything — see Writing a creature. The arrow buttons on the settings page export one as a .zip and import one someone sent you; an import shows you what's inside before installing anything, since it runs their code.

/claudlet

claudlet-install links a /claudlet skill into every agent it found:

• /claudlet — attach a pet to this session · /claudlet standalone — an unattached one
• /claudlet <motion> — jump · wave · sing · juggle · float · celebrate · … (list, stop)
• /claudlet setting · wear <creature> · make <description> · export / import
• /claudlet config — or just ask in plain language ("jump when I run Bash")
• /claudlet window <what> — find a window and have the pet fetch it
• /claudlet update

Docs

• Usage & interaction — drag & throw, click-to-focus, tray menu, motions, autostart
• Configuration — remap which animation shows for which activity
• Writing a creature — the contract, the motion/prop tools a creature inherits, rendering traps
• Platform support — support matrix + how to test on your OS
• Contributing — dev setup, tests, branch model
• Changelog

Contributors

• @htto0824 — dock placement (corner slots, multi-pet alignment, drag-to-move the whole row) and Windows Terminal tab focus
• @Rio-Kyeong — art pixels snapped to the whole-pixel grid (crisp edges, no silhouette wobble as the pet bobs)
• @pawprint0706 — Windows fixes: the no-go zone editor took no mouse input at all, and skill-link junctions were re-warned about on every install
• @reujea — point at something on screen and ask about it (reads the window's text, redacts it, sends only on approval), and the log of what was asked and answered

License

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