A fox who sits on your screen and tells you what your Claude Code sessions are doing — while they're doing it.
Run more than one Claude Code session 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. Foxbot puts a small fox on your desktop who glows blue while a session works, turns amber and keeps asking until you answer a question, and goes green when it lands — with how long it took and what it cost in tokens.
Setup · What he does · Questions · Live notes · Cost · CLI · How it works · Security
macOS only.
git clone https://github.com/svaka2000/foxbot.git
cd foxbot && ./install.shThat installs Hammerspoon via Homebrew if you don't have it, puts the fox in
~/.hammerspoon/foxbot/, the hook in ~/.claude/hooks/, and the foxbot
command in ~/.local/bin/. Your existing hooks are left alone — settings.json
is backed up first and the installer only ever appends.
Then check him:
foxbot doctorNo macOS permissions are required. Hammerspoon asks for Accessibility on first launch because Hammerspoon always does; the fox doesn't use it. Dragging polls the mouse specifically so it works with that permission refused.
Or paste this into Claude Code and let it do the whole thing
Install Foxbot from https://github.com/svaka2000/foxbot
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 there, git pull instead.
2. Run ./install.sh and show me any errors. It installs Hammerspoon via Homebrew
if missing, copies the fox to ~/.hammerspoon/foxbot/, the hook to
~/.claude/hooks/foxbot.sh, and the `foxbot` CLI to ~/.local/bin/. Then it wires
the hook into my ~/.claude/settings.json under UserPromptSubmit, PostToolUse,
Stop, SessionEnd, Notification and PreToolUse — WITHOUT removing hooks I
already have. It backs that file up first; tell me where the backup went.
3. Confirm Hammerspoon is running (pgrep -x Hammerspoon) and that the fox appeared
on the right edge of my screen. He sets launch-at-login himself, so don't
change any Hammerspoon preferences by hand.
4. Print the hook entries from settings.json so I can see my own are still intact
alongside the new ones.
5. Run ~/.local/bin/foxbot doctor and show me the output. Every line should say ok.
6. Do NOT enable Hammerspoon's AppleScript bridge. It is off by default on
purpose and the install doesn't need it.
Then tell me in a few lines: where he is on screen, how to drag him, how to open
his menu, the hide/show and stats shortcuts, and how to get him back if I quit.
I do NOT need to grant Accessibility — say so if Hammerspoon warns about it.
Sessions already running pick the hooks up automatically. Next turn you send, he goes blue; when it lands he tells you which one:
payments-api
4m 12s · 51.5kfinished. · committed: add password reset · edited login.ts, token.ts
Click the note to jump to that session's terminal tab, or use the buttons along the bottom to open the folder, open it in your editor, or copy the summary.
| Live status | blue while a session runs, and a count in the menu bar |
| Won't let you miss a question | stays amber and keeps reminding you |
| Per-turn timing and cost | 4m 12s · 51.5k, from the real transcript |
| What actually changed | summaries built from files and commands, not prose |
| Live progress notes | rate-limited, never repetitive |
| One dial for noise | needed / normal / chatty, instead of nine switches |
| A focus timer | 25 and 5, in the menu bar, never auto-starting the next |
| Notices you've drifted | opt-in, and only when something's actually waiting |
| Teaches you things | ~60 shipped tips, never repeating until you've seen them all |
| Shows you around | a five-step tour the first time, then never again |
| Today / this week | turns, time, tokens, per-project, streaks |
| Donuts | earned by working, spent on how he looks — never on what he does |
| Any terminal | iTerm, Ghostty, WezTerm, Warp, kitty, Alacritty, VS Code, Cursor, Zed |
| Quiet hours | plus automatic silence while you're screen sharing |
| Catch-up | one summary when you come back, not eleven stale notes |
| Per project | mute or re-voice a noisy one |
| Your own sprite | drop a PNG in assets/, one per mood if you like |
| A CLI | foxbot today, now, week, donuts, doctor |
| Always recoverable | foxbot show brings him back without touching the panel |
Ten of them.
| Mood | When |
|---|---|
| resting | nothing running |
| working | a turn is underway |
| deep in it | that turn has been going five minutes |
| waiting on you | a question is unanswered — stays until you deal with it |
| just finished | a turn landed |
| pleased with itself | twenty-five turns in a day |
| something broke | a failure |
| long day | three hours of work behind you, nothing running |
| dozing | you're away from the machine |
| asleep | the small hours, nothing running |
Every one is driven by something real — if he looks tired it's because you've had a long day, and if he's asleep it's because it's 2am and nothing is running. Precedence is deliberate: blocked beats running, running beats the clock, and the ambient states only get a look in when nothing is happening.
Each mood can have its own drawing (foxbot-sleeping.png and so on). Any
you haven't drawn fall back to the default and express themselves through the
badge and how he moves instead, so a half-finished set still works.
One prompt that draws all nine → — paste it into
ChatGPT with his current sprite attached, and you get back a 3×3 sheet:
python3 tools/slice_sheet.py ~/Downloads/sheet.pngThat cuts the sheet into the nine files. It finds the poses by looking for the empty gutters between them rather than assuming exact thirds, because image models never lay a grid out evenly — and anything floating beside a pose, a "z" or a question mark, stays with it.
(If you'd rather do them one at a time, the individual prompts are here.)
Click him — or the menu bar icon — and you get a drawn panel rather than a system menu: a live status header, today's numbers across the top, real switches, and his own colours. A system menu can't carry any of that, which is most of what makes it worth opening.
Sub-pages open in place with a back row, so you don't lose your footing.
One dial, in Settings → How much he speaks up:
| he says something when | |
|---|---|
| only when needed | a session is blocked on you, or something broke |
| normal (default) | …and when a turn finishes |
| chatty | …and what he's doing as he does it |
This started as nine separate switches, each individually reasonable. Measured over an ordinary hour they produced 49 notes, 22 of them announcing that a session had closed. Turn-starts and session-closes now produce no note at any level — the ring and the menu bar already carry that, and "a session closed" is the least actionable thing anything can interrupt you with. The same hour now produces six.
Twenty-five minutes, then five, with a longer rest every fourth block. It runs in the menu bar next to the session count.
He already knows whether you're actually working, so this is less of a bolt-on than it sounds — but it is deliberately not a tracker, not a streak, and not a to-do list. When a block ends it tells you once and offers the next one. It never starts the next one by itself: a break you didn't ask for is where nagging begins.
Settings → Attention. Off by default.
macOS hands out the frontmost app's identity for free. It does not hand out window titles without Screen Recording — and Screen Recording, once granted, lets the holder read everything on your display, including other people's messages and anything in a password field. Foxbot doesn't ask for it and never will.
So he can know you're in Discord. He cannot know which channel. The honest consequence is that browsers are opaque: "Google Chrome" might be the docs or it might be Twitter, so browsers are not counted unless you say so yourself.
When it's on, he needs all of the following before he says anything:
- the app is one marked as a break;
- you've been in it continuously, not just passed through (5 minutes, adjustable);
- and something is actually waiting — a focus block you started, or a session blocked on a question.
That last one is the point. Being on Discord at 9pm with nothing running is not a problem, and a tool that treats it as one is a tool you turn off. At most one nudge in 45 minutes, three a day, never while you're away.
Editing the list needs no typing: open the panel while in an app and it offers that app as a row. His own window is ignored by the sampler, so opening the menu doesn't reset the clock it's about to show you.
He ships with about sixty things he can tell you — git, the shell, macOS,
Claude Code, computing history, and a few facts that are simply good. Drawn
without replacement: you'll see every one before you see any of them twice.
(pack[random(#pack)] repeats within a dozen draws, and a tool that says
something charming and then repeats it stops being charming immediately.)
He volunteers one a day, at the end of a work block — the one moment he knows you're stopping anyway. Ask for as many as you like from Settings → Attention → Tell me something now.
Optionally, and off unless you turn it on, he can ask a hosted model for a
tip about the languages in the project you're actually in. That needs a key you
put at ~/.claude/foxbot/groq.key and the switch turned on, it sends nothing
but file extensions, and every failure falls back to the shipped pack. It is the
only thing in the project that leaves your machine — see
SECURITY.md for exactly what is sent and what CI enforces.
The first time he starts, he walks you through it: where he is, that you can drag him, that clicking opens the panel, what the ring colours mean, and how to make him be quiet. Five short notes, each waiting for you to actually do the thing before moving on.
It gives up gracefully. If you ignore it, it tries at most three launches and then stops for good rather than greeting you forever.
He earns them while you work, and they buy things that change how he looks and nothing else.
The obvious rule — more tokens, more donuts — is the wrong one, because it pays you to burn tokens, which is the one behaviour a tool like this must never encourage. So the unit is the turn: at least one donut however small, plus one per 8k output tokens, and the token part stops counting at 40k. Past that a bigger turn earns nothing extra, so five tight turns beat one bloated one. Sixty a day maximum, so leaving something running overnight is worth nothing. Bonuses for showing up, finishing a focus block, and answering a blocked question quickly.
Cosmetics only. Never behaviour. Nothing in the shop changes what he does — no note you'd otherwise not get, no stat you can't otherwise see, no setting held back. Putting function behind a grind turns a tool into a game that occasionally helps you work.
On the shelf: four palettes, three sound packs, a nameplate. Animals stock
themselves — drop a sprite sheet in assets/ and the shop offers it, because a
shop listing something it can't hand over is worse than a small one. The
reasoning in full, and the prices, are in docs/DONUTS.md.
This is the failure the whole thing exists to prevent. A note 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:
- He 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 repeated at 1m, 5m and 15m, then every fifteen minutes. Abandoned after six hours, on the assumption that terminal is gone.
- The clock runs from the first question, not the latest, so a follow-up doesn't reset how long you've been holding it up.
He tells you what's being applied to the project as it happens — not a play-by-play, a periodic digest:
foxbot committed: rewrite the panel as one canvas · edited panel.lua, sprite.lua · ran the tests
That one note covers four tool calls. The whole feature is built around shutting up, because a pet that narrates everything is a pet you uninstall:
| Rule | Why |
|---|---|
| One note per 2 minutes | a busy minute is still one note |
| Four per turn, ever | a marathon turn can't produce thirty |
| 20-second settle first | so a build two seconds before a commit can't take the headline and block it |
| A 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 |
| Silent while away, hidden, muted, presenting, or in quiet hours | every gate applies |
| No sound, no hop, 7s fade | ambient, not attention-grabbing |
The headline is whatever mattered most, not what happened last — ranked deploy → commit → migrate → delete → push → merge → tests → build → install.
Claude Code's transcripts record token usage per message, so a finished note can say what the work actually took. 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. 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, not a sum.
$ foxbot today
foxbot · 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
today · week · now · recent [n] · projects · export [--csv] ·
doctor. It only ever reads.
Claude Code fires hooks. Each runs ~/.claude/hooks/foxbot.sh, which reads the
payload on stdin and appends at most one JSON line to
~/.claude/foxbot/inbox.jsonl. Hammerspoon tails that file.
| Hook | Meaning |
|---|---|
UserPromptSubmit |
a turn started — start the clock |
PostToolUse |
something was applied — coalesced, mostly discarded |
Stop |
the turn finished — stop the clock, write the ledger |
PreToolUse (AskUserQuestion|ExitPlanMode) |
a question is on screen |
Notification (idle_prompt) |
waiting on you |
SessionEnd |
the session closed |
Pairing the first two with Stop is where the live status, every duration and
every cost figure comes from.
Cost on your hot path: PostToolUse fires on every tool call, so the boring
majority — reads, searches, listings — is thrown away by a shell pattern in
~7ms, before Python ever starts. Only a qualifying call pays the full ~37ms,
and those are rare by design.
error is supported 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/foxbot.sh" error.
~/.hammerspoon/foxbot/ the fox
~/.claude/hooks/foxbot.sh the hook
~/.local/bin/foxbot the CLI
~/.claude/foxbot/inbox.jsonl events in
~/.claude/foxbot/ledger.jsonl finished turns, for the numbers
Drop any PNG into ~/.hammerspoon/foxbot/assets/ and pick it under Sprite.
Aspect ratio is kept, so a tall drawing stays tall, and deleting the one you
were using falls back to the bundled fox rather than leaving a hole.
If your image came out of an image generator, run it through the importer first:
python3 tools/import_sprite.py ~/Downloads/my-fox.png --name my-foxGenerators hand back "pixel art" that isn't — rendered at high resolution with soft anti-aliased edges and tens of thousands of colours, plus a faint halo where the background was keyed out. At 96 points that reads as mush. The importer crops to the artwork, discards the halo, snaps every pixel to a small palette, and writes it at twice the display size so it stays sharp on a Retina screen. The bundled fox goes from 65,984 colours to 8.
There's also a fox authored as a pixel grid in code, if you'd rather edit one a pixel at a time than draw it:
python3 tools/draw_fox.py # writes assets/classic.pngbrew install lua
lua tests/run.lua # 179 unit tests
./tests/hook.sh # 65 integration tests against the real hookThe hook tests drive the actual script against a throwaway HOME. Most of them assert that it stays quiet — that's the whole judgement call of the live notes. Others exist because of specific bugs: the shell pre-filter must stay a superset of the patterns Python matches, or a signal is discarded before Python runs and the only symptom is a note that silently never mentions it.
CI runs both 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 foxbot doctor.
He didn't appear. Hammerspoon menu bar icon → Console, look for a red line.
foxbot.state() in that console prints everything he currently thinks.
He's stuck on "working". A session that never reported finishing is retired after 30 minutes.
Lost him off-screen. ⌃⌥⌘F twice. If a monitor went away,
defaults delete org.hammerspoon.Hammerspoon foxbot.settings resets him.
Nothing happens. grep foxbot ~/.claude/settings.json, then
tail -f ~/.claude/foxbot/inbox.jsonl.
MIT — see LICENSE.
