A little guy who sits on your screen and tells you what your Claude Code sessions are doing — while they do it, not just after.
Run several Claude Code sessions at once and you lose track of which one is thinking, which one finished, and which one has been quietly blocked on a question for twenty minutes. Clawde puts a draggable pixel Claude on your desktop who glows blue while a session works, turns amber and keeps nagging until you answer a question, and goes green when it lands — with how long it took and what it cost.
Setup · vs. the original · Moods · Live notes · Questions · Stats · Cost · CLI · Personalities · Sounds · How it works · Troubleshooting · Security
Built on top of mattypark/claudeaiagentreminderguy, which is where the sprite, the speech-bubble stack and the drawn menu come from.
macOS only. Two ways in — paste one prompt, or do it by hand.
Open Claude Code anywhere and paste this. It does everything: installs, wires the hooks, migrates you off the original pet if you had it, and checks its own work.
Install the Clawde desktop pet from https://github.com/svaka2000/clawde
Do all of it, don't ask me to run anything myself:
1. Clone the repo into ~/Downloads/current-projects (create the folder if needed).
If it's already cloned there, git pull instead.
2. Run ./install.sh and show me any errors. It installs Hammerspoon via Homebrew
if missing, copies the pet to ~/.hammerspoon/clawde/, the hook to
~/.claude/hooks/clawde.sh, and the `clawde` CLI to ~/.local/bin/. Then it wires
the hook into my ~/.claude/settings.json under UserPromptSubmit, Stop,
SessionEnd, Notification, PreToolUse and PostToolUse — WITHOUT removing hooks
I already have.
Back that file up first and tell me where the backup went.
3. If I already had the older claudepet installed, the installer retires its hooks
so I don't end up with two pets shouting at once. Tell me whether that happened.
4. Hammerspoon only loads the pet at startup, so if it was ALREADY running the new
config isn't live yet — restart it (pkill -x Hammerspoon, then open -a Hammerspoon).
Confirm it's up with pgrep -x Hammerspoon and that the pet appeared on the right
edge of my screen. The pet turns on launch-at-login itself, so don't change any
Hammerspoon preferences by hand.
5. Verify my existing hooks still run — print the UserPromptSubmit/Stop/SessionEnd/
Notification/PreToolUse/PostToolUse entries from settings.json so I can see mine are intact
alongside the new ones.
6. Run ~/.local/bin/clawde doctor and show me the output. Every line should say ok.
7. Do NOT enable Hammerspoon's AppleScript bridge. It's off by default on purpose
and the install doesn't need it.
Then tell me in a few lines: where the pet is on screen, how to drag him, how to
open his menu, the hide/show and stats shortcuts, and how to reopen him if I quit.
I do NOT need to grant Accessibility — say so if Hammerspoon warns about it.
That's the whole setup. Skip to the moods.
Option 2 — do it by hand (4 steps)
1. Get the code
git clone https://github.com/svaka2000/clawde.git
cd clawde2. Run the installer
./install.shIt installs Hammerspoon if you don't have it, copies the pet into
~/.hammerspoon/clawde/, the hook into ~/.claude/hooks/, and the clawde
command into ~/.local/bin/. It wires six hooks into ~/.claude/settings.json
and turns on launch-at-login.
Your existing hooks are left alone — the file is backed up first, and the
installer appends to hook groups rather than replacing them. If you had the
original claudepet, its hooks are retired so you don't get two pets; pass
--keep-claudepet if you'd rather run both.
3. If Hammerspoon was already running, restart it
Hammerspoon loads the pet at startup, so an existing instance won't have it yet.
pkill -x Hammerspoon && open -a HammerspoonIgnore the red "Accessibility is not enabled!" warning. This project needs zero macOS permissions — dragging polls the mouse precisely so it works without them.
4. Check that he's alive
clawde doctorEvery line should say ok. The pixel guy should be on the right edge of your
screen — click him and a menu opens; pick Test bubble and a card pops out.
Nothing there? See Troubleshooting.
Either way, you're done. Sessions already running pick the hooks up automatically — no restart. Next time you send a turn he goes blue, and when it lands he tells you which one:
payments-api-refactor
4m 12s · 51.5ksession is done — go look at it.
Click the card and that session's terminal tab jumps to the front — or use the buttons along the bottom to open the folder, open it in your editor, or copy the summary. The small ✕ dismisses without going anywhere.
The original pet was reactive: it spoke after a session finished. In between prompts you had no idea whether Claude was thinking, waiting, or had quietly died. Clawde tracks the whole turn.
| Original | Clawde | |
|---|---|---|
| Knows a session is running | ✗ | ✓ blue ring + menu-bar count |
| Says what's being applied, live | ✗ | ✓ rate-limited digest, max 4 a turn |
| Won't let you miss a question | ✗ 12s bubble, then gone | ✓ stays amber, reminds at 1m/5m/15m |
| How long a turn took | ✗ | ✓ on the card and in stats |
| What a turn cost | ✗ | ✓ output tokens, subagents, peak context |
| Stats | ✗ | ✓ Today page: turns, time, tokens, per-project, 7-day, streak |
| History survives a restart | ✗ (8 in memory) | ✓ on disk, 30-day retention |
| Away digest | ✗ | ✓ one card instead of eleven stale ones |
| Hidden mode | ✗ silently drops the message | ✓ falls back to a macOS notification |
| Non-Terminal.app terminals | ✗ opens a stray Terminal | ✓ iTerm, Ghostty, WezTerm, Warp, kitty, Alacritty, VS Code, Cursor, Zed… |
| Card actions | ✗ | ✓ terminal · folder · editor · copy |
| Quiet hours | ✗ | ✓ + auto-silent while screen sharing |
| Per-project rules | ✗ | ✓ mute or re-voice a noisy project |
| Multi-monitor | ✗ bubbles land on the wrong screen | ✓ follows the sprite |
| Terminal CLI | ✗ | ✓ clawde today · now · week · doctor |
| Uninstaller | ✗ | ✓ ./uninstall.sh |
| Custom sprites | ✗ | ✓ drop a PNG in assets/, pick it in the menu |
| Tests | ✗ | ✓ 154 unit + 33 integration, in CI |
- Launch-at-login kept turning itself back on.
configuredwas missing from the state module's key list, so it was silently dropped on every save. The "run once" preferences block therefore ran on every launch, re-applyinghs.autoLaunch(true)even if you had deliberately turned it off. - Bubbles landed on the wrong monitor. Cards and menus measured themselves
against
mainScreen()while the sprite clamped to whichever screen you dragged it to. - Everyone got Terminal.app. Clicking a card in iTerm or Ghostty opened a brand new Terminal window instead of your session.
- Cards titled "T". An unnamed session falls back to the last component of
its working directory. Short-lived helper sessions run in the macOS temp
directory —
/private/var/folders/…/T— so they produced a stream of cards titledT, several a minute, saying nothing. Temp-directory sessions are now ignored entirely, and a session run from your home folder no longer produces a card named after your username (or a stats bucket named after it either).
One sprite, five states. Rather than ship five drawings that drift out of sync, the mood is a coloured ring plus a change in how he moves — readable across a room, out of the corner of your eye.
| Ring | Mood | When |
|---|---|---|
| — | idle | nothing running |
| 🔵 blue, breathing fast | working | a session is mid-turn |
| 🟡 amber, pulsing | asking | a question is unanswered — stays until you deal with it |
| 🟢 green | done | turn finished |
| 🔴 red | error | wire it yourself, see below |
⌃⌥⌘T, or click him → Today.
TODAY
Turns 14
Working time 2h 14m
Sessions 3
Streak 6d
WHERE IT WENT
payments-api ████████████ 1h 22m
landing-page █████ 38m
infra ██ 14m
LAST 7 DAYS
Thu ███████ 12 · 1h 40m
Fri ████████████ 21 · 3h 02m
...
All of it is derived from the history log — there is no second source of truth.
He tells you what's being applied to the project while it happens — not a play-by-play, a periodic digest:
clawde committed: add password reset flow • edited login.ts, token.ts • built it
That single bubble represents four tool calls. The whole feature is built around shutting up, because a pet that narrates every action is a pet you uninstall:
| Rule | Why |
|---|---|
| One bubble per 2 minutes, per session | a busy minute is still one bubble |
| Four per turn, ever | a marathon turn can't produce thirty |
| 20-second settle before the first | so a build 2s before a commit doesn't win the headline and block it |
| Milestone or ≥3 files | one edited file isn't news |
| Never repeats itself | identical text to last time is dropped |
| Silent while you're blocked | a question already needs you; noise on top is worse |
| Silent while away, hidden, muted, presenting, or in quiet hours | reuses every existing gate |
| No sound, no hop, 7-second fade | ambient, not attention-grabbing |
The headline is whatever was most significant, not most recent — ranked deploy → commit → migrate → delete → push → merge → tests → build → install. Everything else becomes a bullet.
It reads real signals, not guesses: git commit (with the subject line),
pushes, merges, test runs, builds, installs, deletes, migrations, deploys, and
edited files grouped by directory. Nothing is inferred about intent.
Cost on your hot path: PostToolUse fires on every tool call, so the boring
majority — Read, Grep, Glob, ls, cat — is discarded by a shell pattern
in ~7ms before Python ever starts. Only a qualifying call pays the full
~37ms, and those are rare by construction.
Turn it off under Live progress notes.
This is the failure the whole thing exists to prevent. A bubble lasts twelve seconds. If you were in another window when Claude asked which database to use, the session sits blocked indefinitely and nothing on screen says so.
So a question marks the session as waiting until something actually moves it along:
- The pet stays amber for as long as anything is blocked. Waiting outranks working — something needs you more than it needs to keep going.
- The menu bar shows
?2rather than2. - Unanswered questions are said again at 1m, 5m, 15m, and every 15 minutes after that. Abandoned at six hours, on the assumption that terminal is gone.
- The blocked clock runs from the first question, not the latest, so a follow-up doesn't reset how long you've been holding it up.
Turn it off under Remind me about questions if you'd rather it didn't.
Claude Code's transcripts record token usage per message, so a finished card can
say what the work actually took: 4m 12s · 51.5k.
Two things make that harder than summing a column, and both are handled:
- Assistant entries are rewritten repeatedly as a message streams, so the
same tokens appear several times over. They're deduplicated by
message.id, keeping the last write. - A "turn" has to end somewhere. It ends at the last real user prompt —
a user entry whose content isn't a
tool_result.
Subagent output is counted separately, and peak context is a max rather than a
sum. Only computed on done; the busy path never touches the transcript.
Come back from lunch to eleven stacked cards and the one that mattered has already scrolled off the top. So while you're away the pet holds everything and hands it back as a single card: turns finished, time worked, who's waiting.
Away means locked or asleep — nothing else, by default. Input idle time is a tempting signal and a bad one: sitting and watching a long turn scroll past registers as zero input, so an idle-based rule goes quiet exactly when you're looking at it. You can opt into 15- or 30-minute idle anyway under Away digest → Away means.
Hidden is not the same as away. With the sprite hidden he still tells you — through a normal macOS notification instead of a bubble.
install.sh drops a clawde command into ~/.local/bin.
$ clawde today
clawde · today
turns 14
working 2h 14m
sessions 3
tokens 412.0k
streak 6 days
where it went
payments-api ██████████████···· 1h 22m 210.4k
landing-page █████············· 38m 88.1k
clawde / clawde today |
what happened today |
clawde week |
the last seven days |
clawde now |
sessions running right now |
clawde recent [n] |
the last n sessions |
clawde projects |
every project, ranked by time |
clawde export [--csv] |
the whole history on stdout |
clawde doctor |
check the install |
It only reads — same files the pet uses, never writes to them.
Every card carries a row of buttons:
- terminal — jump to the exact tab that session ran in
- folder — reveal the project in Finder
- editor — open it in VS Code / Cursor / Zed / Sublime, whichever you have
- copy — put the summary on your clipboard
Clicking the card body does the same as terminal. The ✕ just dismisses.
He keeps tracking, he just stops interrupting.
- A time window (default 22:00 → 08:00), wrapping midnight properly.
- Silence only keeps the cards but kills the sound; the default hides both.
- Automatic while Zoom, Teams, Webex, Meet, Keynote, OBS or QuickTime has a visible window. Nothing pops up mid-demo.
Click him → Per-project. Every folder you've run a session in shows up. Mute the noisy one; the rest keep talking.
| Drag him | click and hold, anywhere on screen — he remembers |
| His menu | single click |
| Menu bar | the icon top-right, always there; shows a count while working |
⌃⌥⌘P |
hide / show |
⌃⌥⌘T |
today's stats |
Hidden vs quit. Hidden means the sprite is gone but he still tracks
everything and still plays sounds. Quit means Hammerspoon exits and nothing is
recorded. open -a Hammerspoon brings him back.
Seven, each with a few variants so he doesn't say the same line twice in a row.
Direct, Kind, Hype, Chill, Butler, Gremlin, Feral.
Direct "payments-api · session is done — go look at it."
Butler "payments-api · has concluded its work. At your convenience."
Gremlin "payments-api · done. i did the thing o7"
Feral "payments-api · DONE!! it's done!! come here!! come LOOK!!"
How much of what the session actually did to show:
- Just the name — one line
- Summary — three bullets
- Full recap — up to six, including what's left to do
Question cards ignore this and always show every option, because the options are the message.
Drop any PNG into ~/.hammerspoon/clawde/assets/ and pick it under Skin.
Aspect ratio is preserved, so a tall drawing stays tall. Delete the file you
were using and he falls back to the bundled sprite rather than vanishing.
The skin is used for the menu bar icon too.
A sound per event — done, asking, waiting, started, error, closed. Pick from the
macOS system sounds or drop your own .mp3 / .m4a / .wav / .mp4 into
~/.hammerspoon/clawde/sounds/ and hit Reload pet.
Claude Code fires hooks. Each one runs ~/.claude/hooks/clawde.sh, which reads
the payload on stdin and appends one JSON line to
~/.claude/clawde/inbox.jsonl. Hammerspoon tails that file.
| Hook | Kind | Meaning |
|---|---|---|
UserPromptSubmit |
busy |
you sent a turn — start the clock |
Stop |
done |
the turn finished — stop the clock, write history |
PreToolUse (AskUserQuestion|ExitPlanMode) |
ask |
a question is on screen |
PostToolUse |
step |
something was applied — coalesced, see above |
Notification (idle_prompt) |
idle |
waiting on you |
SessionEnd |
end |
session closed |
Pairing busy with done is where the live status and every duration comes
from. Nothing else changes about how you use Claude Code.
error is supported by the pet but not wired by the installer, because Claude
Code has no reliable "this turn failed" signal to hang it on. If you have your
own way of detecting failure, point a hook at
bash "$HOME/.claude/hooks/clawde.sh" error and he'll go red.
- The session's name — your
/rename, or the title Claude generated. - The transcript's
ai-title, if the session record hasn't caught up. - The project folder.
The hook walks up the process tree from the session's pid until it recognises a
terminal, matching on the .app bundle name rather than the executable — which
is what makes Warp work, since its binary is called stable. Terminal.app and
iTerm2 additionally get an exact tab match by tty; everything else is raised to
the front.
~/.hammerspoon/clawde/ the pet
~/.claude/hooks/clawde.sh the hook
~/.local/bin/clawde the CLI
~/.claude/clawde/inbox.jsonl events, appended by the hook, tailed by the pet
~/.claude/clawde/history.jsonl finished turns, for the stats
Settings live in Hammerspoon's own preferences under clawde.state.
./install.sh does it for you: it imports your position and preferences,
comments out the old require, and retires the old hooks so you don't get two
pets shouting at once. Pass --keep-claudepet if you'd rather run both.
./uninstall.sh # removes the pet, keeps your history
./uninstall.sh --purge # removes the history and settings tooIt only ever deletes hook entries it can see are its own, and backs up
settings.json first.
brew install lua
lua tests/run.lua154 Lua assertions over session pairing, duration maths, token formatting, stats aggregation, history retention, quiet-hour windows, away detection, question nudge escalation, skin fallback, the claudepet migration, and the settings round-trip that the original got wrong. Anything that draws is out of scope.
./tests/hook.sh adds 33 integration tests that drive the real hook against a
throwaway HOME — most of them about when the live progress notes should stay
quiet, since that is the whole judgement call of the feature.
CI runs them on every push, and additionally fails the build if a network call appears anywhere, or if the AppleScript bridge is ever enabled by default.
Start with clawde doctor — it checks the pet, the hook, the wiring, whether
Hammerspoon is running, and whether the old claudepet is still hanging around.
He didn't appear. Hammerspoon menu bar icon → Console, look for a red line.
clawde.debug() in that console prints everything he currently thinks.
He's stuck on "working". A session that never reported finishing gets
retired after 30 minutes. Working now in the menu shows what he thinks is live.
Lost him off-screen. ⌃⌥⌘P twice, or the menu bar icon → Hide/Show. If a
monitor went away, defaults delete org.hammerspoon.Hammerspoon clawde.state
resets his position (and only his position).
Nothing happens when a session ends. Check the hook is wired:
grep clawde ~/.claude/settings.json. Then check events are landing:
tail -f ~/.claude/clawde/inbox.jsonl.
macOS · Hammerspoon · Claude Code. Everything works in any terminal; exact tab-switching needs Terminal.app or iTerm2.
No network access of any kind. Credentials are redacted before anything is written to disk or drawn on screen. Hammerspoon's AppleScript bridge is left off — the installer never enables it. See SECURITY.md.