Skip to content
svaka2000Public

About

A desktop pet that watches your Claude Code sessions — live status while they run, not just after. Moods, per-turn timing, stats, multi-terminal focus. macOS/Hammerspoon.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

13 Commits

Folders and files

Repository files navigation

Clawde

Clawde

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.

ci

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.


Setup

macOS only. Two ways in — paste one prompt, or do it by hand.

Option 1 — paste this into Claude Code

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 clawde

2. Run the installer

./install.sh

It 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 Hammerspoon

Ignore 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 doctor

Every 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.5k session 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.


What it does that the original didn't

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

Bugs fixed from the original

  • Launch-at-login kept turning itself back on. configured was 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-applying hs.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 titled T, 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).

The moods

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

Today

⌃⌥⌘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.

Live progress notes

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.

It won't let you miss a question

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 ?2 rather than 2.
  • 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.

What a turn cost

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.

While you were away

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.

From the terminal

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.

Card actions

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.

Quiet hours

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.

Per-project rules

Click him → Per-project. Every folder you've run a session in shows up. Mute the noisy one; the rest keep talking.


Controls

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.

Personalities

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!!"

Bubble detail

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.

Make him your pet

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.

Sounds

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.


How it works

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.

Where session names come from

  1. The session's name — your /rename, or the title Claude generated.
  2. The transcript's ai-title, if the session record hasn't caught up.
  3. The project folder.

Which terminal a session belongs to

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.


Files

~/.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.

Upgrading from claudepet

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

Uninstalling

./uninstall.sh            # removes the pet, keeps your history
./uninstall.sh --purge    # removes the history and settings too

It only ever deletes hook entries it can see are its own, and backs up settings.json first.

Tests

brew install lua
lua tests/run.lua

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

Troubleshooting

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.

Requirements

macOS · Hammerspoon · Claude Code. Everything works in any terminal; exact tab-switching needs Terminal.app or iTerm2.

Security

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.

About

A desktop pet that watches your Claude Code sessions — live status while they run, not just after. Moods, per-turn timing, stats, multi-terminal focus. macOS/Hammerspoon.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages