claudetop
A little pixel Claude that lives at the bottom of your screen and shows what Claude Code is doing.
| State | What Claude does |
|---|
| Working | walks around (or taps away in place) with a "Working…" bubble |
| Needs you | bounces and waves: Claude is waiting on a permission or question |
| Done | hops and says "Done! ✓" until you've seen it (see below) |
| Out of credits | turns grey and deflates (billing / usage-limit errors); hover to see when the limit resets |
| Tokens are back | when that reset time passes: a jolt of colour, then it glows with charge until you look |
| Resting | sits down and snoozes |
When "Done" goes back to resting: if you're already in the Claude Code window when it
finishes, after 10 seconds. If you're somewhere else, it keeps saying "Done!" until you switch to
Claude Code, then rests 5 seconds later. A terminal tab counts as Claude Code when it belongs to
the session or its title looks like a Claude Code title (✳ topic, ◑ topic, or contains "Claude").
Extras (right-click menu)
- Panic when done: when Claude finishes while you're elsewhere, the little Claude sprints back
and forth across all your monitors, wide-eyed and sweating, until you open Claude Code. Then it
sighs with relief (dropping and picking up its hard hat, if it has one) and walks home.
- Hat: none, a yellow hard hat, a propeller beanie whose propeller spins while it moves, or a
miner hat with a headlamp: a miner digs down and tunnels instead of walking long distances.
Or go full Agent 47: black suit, red tie, barcode, sneaking at 47 px/s, and his own lines
("On a contract…", "Mission accomplished.").
- Watch TV when you watch videos: while a video plays, Claude sits down in front of a little
TV. If Claude Code finishes mid-show, it jumps up and kicks the TV across all your screens.
- Dance to music: when music plays (Spotify and other music apps, or anything incl. browser
videos), Claude puts on headphones and dances with colourful notes floating around.
- Cry when you open another AI: switch to ChatGPT, Gemini, Copilot, Perplexity, Grok, DeepSeek
or friends (browser tab or app) and Claude bursts into tears for a few seconds. Once a minute at most.
- Click to jump: click the little Claude to bring up the terminal or editor its session runs in.
- One Claude per session: other active sessions get smaller Claudes of their own colour; click
one to jump to that session. Each wears a hat of its own (scroll over it for another).
- Props: while working, Claude holds a magnifying glass (searching), a pencil (editing), a little
terminal (running commands) or a book (reading). After 10 minutes on one task it drinks coffee,
after 30 it crawls into a sleeping bag.
- Rage quit: three failed tool calls in a row and Claude flips a table (then puts it back).
- Game mode: a fullscreen window hides Claude on that screen; on another screen, Claude grabs a
controller and plays along.
- Seasonal surprises: snow in winter, a pumpkin for Halloween week, a Santa hat at Christmas,
party hat and fireworks at New Year, and a cockade on Hungary's national days (with fireworks on
20 August). Only when Claude has no hat of its own.
- Become Agent 47 while Hitman runs: start any Hitman game and Claude suits up; quit it and its
usual hat comes back. Your saved hat isn't touched.
- More hats, each with its own way of getting around and its own lock-in move:
- cowboy hat: rides a horse; lassos the tab ("Yeehaw!")
- wizard hat: teleports on long trips; zaps the tab into a frog that hops away
- pirate hat: sails a little boat; fires a cannon at the tab
- astronaut helmet: low-gravity hops; jetpacks up and launches the tab into space
- ninja headband: dashes in a blur; a throwing star slices the tab
- crown: walks slowly in a royal cape; a guard runs in and spears the tab ("Off with its tab!")
- chef hat: rolls along on a giant meatball; a cream pie to the tab
- Sounds: an 8-bit jingle when work is done, a ping when Claude Code needs you (Agent 47 gets
lower ones).
- Do not disturb: switch it on by hand, or let it switch itself on while any app uses the
microphone (calls, streams). No sounds, panic runs, tears, flipped tables or chatter meanwhile.
- Daily recap: hover the tray icon, or see the top of the menu: tasks finished today, time
worked, tasks without a permission prompt.
- Achievements: 17 of them, some hidden; they pop up as Claude unlocks them. The list is in the
right-click menu.
- Night owl: between midnight and 5 a.m. Claude wears a nightcap, yawns, and tells you to sleep.
- Birthday: set yours in the right-click menu for a party hat, confetti and wishes on the day.
- Throw Claude: drag it up to lift it, let go to drop it, fling it to watch it bounce off the
edges.
- Little things: double-click to pet Claude (ten quick clicks is too many), scroll over it to
change hats, "Snooze sounds for an hour" in the menu, the record day under the daily recap, and
every few minutes of rest Claude reads the paper, juggles or snores. It starts where it last stood.
- Hitman: while a Hitman game runs, 47 cheers you on every so often; when it closes he bows.
- Agent 47 extras: disguises (a chef while editing, a mechanic while tests fail, and a rare
flamingo), and a mission rating after each job: Silent Assassin if it needed no permission prompts.
- Show on screen: pick which monitor it lives on (it walks over).
- Roam across all screens: wander freely over every monitor, hopping across the edges.
Lock-in mode
Off by default; turn it on from the right-click menu. When the browser tab in front has an adult
site or keyword in its title, Claude closes that tab (Ctrl+W) and tells you to lock in. How
depends on the hat: no hat slashes a red line through the tab; a hard hat gets thrown at it (and
fetched afterwards); a propeller flies Claude up to bonk it, which knocks the hat off: Claude
tumbles down and lands flat, the hat flutters down and bonks it on the head, then it gets up, gets embarrassed, angry or sad, picks the hat up and flies back; a miner digs down, peeks
out of the ceiling upside down, whacks the tab with a shovel, falls spinning into a hole in the
floor and tunnels back; Agent 47 lobs a remote explosive rubber duck onto the tab and clicks.
It only reads window and tab titles, never what's on screen.
Install
Run claudetop Setup <version>.exe. The wizard asks where to install and offers a desktop
shortcut, connecting to Claude Code (adds hooks to ~/.claude/settings.json), and starting with
Windows. Uninstalling from Windows Settings removes the hooks again.
The installer isn't code-signed, so Windows SmartScreen may say "Windows protected your PC":
click More info → Run anyway.
Linux
AppImage and .deb builds are attached to every release (built by .github/workflows/linux.yml
when a release is published). See website/linux.html for install steps. It works best on X11;
on Wayland and WSL it can't see other apps' windows, so "done" times out instead of waiting.
Build the installer
npm install
npm run dist # -> dist/claudetop Setup <version>.exe
If the build fails with "Cannot create symbolic link", turn on Windows Developer Mode, or extract
%LOCALAPPDATA%\electron-builder\Cache\winCodeSign\*.7z into a winCodeSign-2.6.0 folder next to it
(the failing symlinks are macOS-only files).
Website
Live at https://benceandrastoth-ply.github.io/claudetop/ (GitHub Pages; website/ is published
by .github/workflows/pages.yml on every push that changes it).
- Branding: name, tagline, colours, your name and links all live in
website/brand.js.
- Publishing a release:
- Bump
version in package.json, then npm run dist.
npm run release -- --notes "First change; Second change": creates the GitHub Release with
the installer attached and puts the version at the top of website/releases.json (the newest
one is what the big download buttons point to).- Commit and push; the site updates by itself.
Develop
npm install
npm run install-hooks # points the hooks at this checkout via node
npm start
Using it
- Hover over Claude to see each session's status.
- Drag to move it. In "Stay in place" mode, the spot is remembered.
- Right-click (or use the tray icon) to switch Walk/Stay in place, preview states, start with Windows, or quit.
How it works
hooks/report.js runs on Claude Code hook events and writes one small JSON file per session to
~/.claude/claudetop/sessions/. The Electron app watches that folder and picks the most important
state across all sessions: needs you > working > latest of (out of credits / done / error) > resting.
Remove the hooks with npm run uninstall-hooks.
