A local dashboard for keeping an eye on your coding-agent sessions while they work.
An isometric office building where every Claude Code session gets a desk, and a red window means someone is waiting for you.
Quick start · ** Demo** · ** Install** · ** The building** · Claude Code mod
Provided by FairMind, and open source under the Apache License 2.0.
Every session gets a desk in an isometric office building: one floor per feature, pods of desks for each checkout, interns for subagents, meeting rooms for workflows, a lounge for idle sessions, and a basement archive for finished work. Robots walk between them as sessions change state. A red window on the façade means someone is waiting for you.
Built for Claude Code (local and cloud) first, with an adapter interface meant to welcome other coding agents.
You need Node 22.13 or later and Claude Code. Install the CLI and the mod:
npm install -g @fairmind-ai/hopper-hq
claude plugin marketplace add FairMind-Gen-AI-Studio/hopper-hq
claude plugin install hopper-hq@hopper-hq
Then type /hopper-hq in any Claude Code session. It starts the daemon if needed and opens the building in your browser. From a shell, hopper-hq up does the same.
No sessions yet? Run hopper-hq demo to watch synthetic ones.
The mod makes hopper-hq report each session as things happen, with the exact reason it waits. It is optional, but recommended: see the mod. For tmux, summaries, upgrading and everything else, read on.
Early. The collector, the CLI, the tmux counter and the building in the browser work, with meeting rooms for workflow runs, interns for subagents, robots that walk between desks, rooms, the lounge and the elevator, and an optional line that says where each session stands. The archive is planned. See the design document, the design of rooms, interns and summaries, and the design of the floor plan and walking.
Watch the demo video (one minute): a floor with three repositories on one feature, a session that needs you, a workflow run in its meeting room, and robots walking between desks. To play it yourself, run hopper-hq demo.
- Shows which sessions work on the same feature. Sessions are grouped by branch, across repos.
- Shows which sessions are waiting for you, and why.
- Shows what runs inside each session: its workflow runs, phase by phase, and its subagents.
- Says in one line where each session stands, once you turn summaries on.
- Keeps a record of finished sessions (coming).
Node 22.13 or later is required. hopper-hq reads the sessions of Claude Code; tmux is optional, and only needed for the status line and the Go buttons.
To see the building before you have any sessions, run hopper-hq demo once it is installed: it plays synthetic sessions, and hopper-hq demo --showcase plays a longer scenario.
Install it from npm:
npm install -g @fairmind-ai/hopper-hq
The command is hopper-hq. To work from a clone of this repository instead, run npm install && npm run build && npm link in it.
Run npm install -g @fairmind-ai/hopper-hq@latest (from a clone: pull, then npm install && npm run build). Then:
- Restart the daemon:
hopper-hq down, thenhopper-hq up. If it runs in the foreground (hopper-hq start), stop it with Ctrl-C and start it again. - Update the mod: with
/pluginin Claude Code, or install it again as inThe Claude Code mod . - Reload every building tab you had open. A tab opened before this upgrade stops following the building without saying so. From now on, a tab that can no longer follow the building says so and asks for the reload.
The first start after an upgrade that brings the floor plan seats every session afresh, once: each takes a desk on its floor's plan, and keeps it from then on, across restarts.
Run hopper-hq up. It starts the daemon in the background if it is not running yet, then opens the building in your browser. The daemon writes its log to ~/.hopper-hq/daemon.log. hopper-hq down stops it.
To run the daemon in the foreground instead, in its own tmux window or terminal, use hopper-hq start. Then run hopper-hq ls, or hopper-hq ui to open the building in your browser.
This already works from the files Claude Code writes, without the mod.
hopper-hq ui signs your browser in and opens the building. The daemon must be running. With --no-open it only prints the link.
The façade has one floor per feature, shared by every repository working on that branch, and one floor per repository for sessions with no feature branch. Floors keep their place, newest on top. Each window is a desk of the floor's plan, so a floor shows from outside how large it is and how full:
| Window | State |
|---|---|
| Red, pulsing | Needs you: a permission, a question or a plan approval is waiting. |
| Green | Done: it finished its turn and waits for you to look. |
| Lit yellow | Working. |
| Purple | In a meeting: idle itself, while its subagents or workflow agents run. |
| Amber, flickering | No signal: working, but nothing new for a while, often a long command. |
| Unlit (grey by day, dark at night) | Idle, or dormant (idle for days). A floor where everyone is dormant lowers its shutters. |
| Unlit, with a frame | A free desk. |
The bar at the top lists who needs you (longest wait first) and what is done (oldest first) at every level. Click an entry to open its desk; Go switches tmux to its pane.
Click a floor to go inside. Each session has a desk and a robot, whose pose and badge show its state. Click a desk or its robot to see what it is doing. Double-click it, press Enter, or use Go to pane to switch tmux to its pane.
A desk's panel also lists the session's interns and its latest workflow runs, with how long each has run and how it ended. With summaries on, it says in one line where the session stands, and so do the desk's row in the floor's side panel and its entry in the bar at the top.
Subagents that a session starts outside a workflow run are its interns: small robots that hover on jetpacks over its desk while they run, three at most. While a session has subagents running, they meet in a room of their own, named Subagents, with the session at the head of the table; the interns hover over the desk only when no room is free.
Each workflow run that is going on, and each session whose subagents run, has a meeting room, in a wing east of the desks on its session's floor:
- its agents sit at the table as robots in hard hats, eight at most;
- the robot of the session that started the run sits at the head of the table while the session works with the run, or waits for it; a session that needs you stays at its desk, where it waves;
- everyone at the table, the session's robot and the agents, has a laptop open in front of them;
- a tag over the door names the run, and adds its current phase and its counts up close or when the room is selected;
- up close, the whiteboard lists the run's phases (✓ done, ● current, ○ upcoming) and how many agents run and have finished.
A floor has two rooms, and four once a third run goes on at the same time; its side panel counts the runs beyond four. A run keeps its room until it ends. The room then closes, its door shut and its lights dimmed, and the session's desk panel keeps how the run ended. Click a room or its tag to open the run's panel: its phases, its agents and a link to the session's desk. Double-click the room, press Enter, or use Go to pane to switch tmux to that session's pane.
The page's address names the floor, and the desk or the run on screen: a link opens it, and Back and reload keep your place.
| Key or gesture | Does |
|---|---|
| Esc | Goes up one level: desk or run, floor, building. |
| Q, E | Turns the floor a quarter left or right. |
| R | Resets the view. |
| Enter | With the floor or the selected desk's or room's label focused, goes to that desk's pane, or for a room to the pane of the session that started its run. |
| Drag, scroll, right-drag | Turns and tilts, zooms and pans the floor. |
| Arrows, Shift + arrows | Once you have clicked the floor, up and down walk ahead and back, and left and right steer. With Shift, up and down tilt the view, and left and right step aside. A focused label keeps the arrows for moving to the next one, and the side panel for scrolling. |
The theme button cycles through system, day and night. A browser without WebGL still lists a floor's desks and meeting rooms in the side panel. When the page can no longer follow the building, because the daemon was updated since it loaded, it says so and asks you to reload it.
Going to a pane switches the most recently used tmux client to it. The daemon talks to the tmux server it was started under, or the default one. It cannot bring the terminal window to the front.
A floor's plan is fixed: desks, meeting rooms and a lounge that sessions take and leave.
- Desks come in pods of four, back to back on a rug, and pods in blocks of two: eight desks to a block.
- A new session sits in a pod where a session of its checkout sits, else at an empty pod, else at the first free desk. It keeps its desk until it ends or moves to another floor.
- A pod's rug takes its repository's colour while all its sessions share one repository. Its placard names their checkout, or only the repository when that is all they share.
- With no desk free, a new session takes the desk of the session that has been dormant longest, which takes a desk again when one frees up or it wakes. With none dormant, the floor grows by a block, up to four blocks: 32 desks. Further sessions wait for a desk: the side panel lists the first 24, marked "no desk", and counts the rest; the façade counts them all.
- A floor never shrinks while it has sessions. Once the last one leaves, it starts again from one block.
- A dormant session's robot goes home. Its desk stays its own, dimmed, with its name on a nameplate that shows closer in. A click on the nameplate selects the session.
- The lounge runs along the south wall, with eight seats on couches and beanbags. An idle session rests there until its next prompt; with the lounge full, it rests at its desk.
Robots walk. A session that comes to a floor steps out of the elevator and walks to its desk; one that ends, goes dormant or moves to another floor walks back into it. As its state changes, a robot walks to its meeting room, to the lounge and back to its desk, round the furniture. Workflow agents walk from the elevator to their seats and back, and interns fly straight to their desk and back. Everyone keeps their seat until they leave. The elevator doors open for each robot that passes.
At rest, robots move a little: a working robot or agent types, one that needs you waves, one that is done holds up its paper, one without a signal dozes, an idle one breathes, and interns bob on their jetpacks.
A floor you open, reload or come back to shows everyone already in place: only what changes while you watch walks. Under your system's reduced-motion setting, robots go straight to their places and nothing moves at rest. So it is with ?motion=off in the page's address (/ui/?motion=off), for screenshots and tests.
-
From far, which is how a floor first shows on most screens, a robot's tag is a dot in its state's colour, named only while it is selected, needs you or is done. Room tags keep their names, and the pods' placards hide.
-
Closer in, every tag and placard shows whole.
-
Where two overlap, the one that ranks lower gives way: the selected tag first, then needs you, done, rooms, working, the other states, and placards last. From far, a named tag that gives way keeps its dot where the dot is clear.
-
Hover or focus a tag to read it whole: it shows on top of the others, and hides none of them, while you do. Free desks and dormant ones have no tag.
-
The daemon listens on 127.0.0.1 only.
-
hopper-hq uiasks the daemon for a one-time link. It works once, within a minute; the demo's link lasts 10 minutes. -
Opening the link sets a signed, HttpOnly cookie for that daemon's port. It lasts 30 days and survives daemon restarts. To sign every browser out, delete
~/.hopper-hq/tokenand restart the daemon. -
A signed-in browser can watch the building, switch tmux panes and mark sessions as seen. It cannot send hook events, ask for sign-in links or stop the daemon. From a browser, changes are accepted only from the daemon's own page.
-
The page loads nothing from the network. Scripts, styles and fonts come from the daemon, under a strict content security policy.
-
Known risk: browsers do not keep cookies apart by port. Any other server on 127.0.0.1 that this browser talks to, such as a dev server an agent started, receives the cookie. It could reuse it for up to 30 days to watch the building, switch your tmux panes and mark sessions as seen. If that matters to you, sign everything out as above.
-
In the demo,
GoandGo to paneare simulated: the page says which pane it would switch to, and tmux is never touched.
Add this to your ~/.tmux.conf:
set -g status-right '#(hopper-hq status --format tmux) %H:%M'
set -g status-interval 5
◉ is the number of sessions waiting for you. ✓ is the number of finished sessions you have not looked at. hopper-hq ack clears the ✓.
The mod reports each session as things happen, with the exact reason a session waits. It also shows, above the prompt of every session, who else is waiting for you. A Go button jumps to that tmux pane.
Type /hopper-hq in any session to open the building. It runs hopper-hq up, so it also starts the daemon when it is not running, and it takes no turn of the model. The sign-in link stays out of the conversation. The Open building button in the band above the prompt does the same; the band shows only while another session waits for you or has finished. Both need hopper-hq on your PATH: see Install.
Install it from a shell:
claude plugin marketplace add FairMind-Gen-AI-Studio/hopper-hq
claude plugin install hopper-hq@hopper-hq
To try it from a clone for one session:
claude --plugin-dir /path/to/hopper-hq/mod
Without the mod, hopper-hq still works from the files Claude Code writes. It has up to a second of delay and less detail about why a session waits.
hopper-hq can write one line per session that says where it stands: what is done, what is in progress, or what it waits for. A language model writes the line, so summaries are off by default. To turn them on:
hopper-hq summaries on
The full form is hopper-hq summaries on|off|status [--provider claude-cli|anthropic-api] [--model <id>]:
onandoffturn summaries on and off, and say what is now set.status, the default, prints the setting and what the running daemon does: its last summary, its last error, and a .--providerchooses where the notes go, below.claude-cliis the default. A--providerwithout--modelgoes back to that provider's default model.--modelnames another model: 1 to 64 letters, digits,.,_,:or-, starting with a letter or a digit. The defaults arehaikuforclaude-cliandclaude-haiku-5-5foranthropic-api.
The setting lives in ~/.hopper-hq/config.json, readable by you only. The daemon reads it again before each summary, so it needs no restart.
The line shows in the desk's panel with its age, under the desk's row in the floor's side panel, and under its entry in the bar at the top. Once you have sent the session a prompt since, its age says "(older than the last prompt)". The line is then dimmed in the panels, and set in italics in the bar.
When a session comes to a stop (it is done, needs you, or waits in a meeting), the daemon waits 8 seconds and reads the session again. Unless it is working again, it asks for a line.
- Only turns that end while the daemon runs are summarized. Notes that have not changed since the last line are not sent again.
- At most one summary per session every 3 minutes, and one at a time across the daemon.
- A failed summary is tried again later, while the session still stands where it did. Each failure makes the session wait longer for its next try: 1 minute, then twice as long each time, up to 30 minutes, and never less than the 3 minutes between two summaries.
- After 3 failures in a row, every summary s for 15 minutes. Changing the provider or the model lifts the .
hopper-hq summaries statusshows the last error and the . The daemon's log gets one line per failure, with the error.
Each summary sends a fixed instruction and these notes about one session, each cut to one line:
- its title;
- its last request: your last prompt, or the first one;
- its state, with what it waits for when it waits: the tool that asks for permission and its command or file, or the question;
- the labels of its last 10 tool calls, such as
Bash: npm testorEdit src/app.ts; - its last reply, up to 2,000 characters.
The notes are cut to about 4,000 characters: the end of the reply goes first, then the oldest actions. hopper-hq sends nothing else.
Where they go depends on the provider:
claude-cli, the default, runsclaude -p --safe-modewith the notes on its standard input. It runs on your account: wherever yourclaudesends its requests.--safe-modestarts it without your plugins, hooks, CLAUDE.md, skills and MCP servers. It gets no tools and saves no session.- It runs in its own directory,
~/.hopper-hq/summarizer, withHOPPER_HQ_SUMMARIZER=1set. The building leaves its sessions out, and the mod reports nothing from it. - Its environment is the daemon's, without
ANTHROPIC_API_KEY, so it is never billed to a key. It also goes without the variables that tie it to a Claude Code session that may have started the daemon:CLAUDECODE,AI_AGENT,CLAUDE_PID,CLAUDE_EFFORT,CLAUDE_PLUGIN_DATA,CLAUDE_PLUGIN_ROOT,CLAUDE_CODE_ENTRYPOINT,CLAUDE_CODE_EXECPATH,CLAUDE_CODE_CHILD_SESSION,CLAUDE_CODE_BRIDGE_SESSION_ID,CLAUDE_CODE_SSE_PORT, and everyCLAUDE_CODE_SESSION_*andCLAUDE_CODE_MESSAGING_*. - Every other variable stays, so
claudesigns in, connects and picks its provider as it does for you:CLAUDE_CODE_OAUTH_TOKEN, a client certificate, a proxy,CLAUDE_CODE_USE_BEDROCKand the like. - It needs
claudeon the daemon'sPATH, and is stopped after 60 seconds.
anthropic-apisends the notes to the Anthropic Messages API, atapi.anthropic.com, with the key inANTHROPIC_API_KEY.- The daemon reads the key from its own environment, which it takes from where you ran
hopper-hq uporhopper-hq start. Set it there, and restart the daemon to change it. - The key is never written to disk. A request gives up after 30 seconds.
- The daemon reads the key from its own environment, which it takes from where you ran
- The daemon reads the key from its own environment, which it takes from where you ran
--safe-mode is a recent option of Claude Code. Once summaries are on, check that a line appears and that hopper-hq summaries status shows the last summary, with no new session in the building.
The demo (hopper-hq demo) writes fixed lines of its own and sends nothing anywhere.
Each summary is one call to the model, a small one by default. A session gets at most one per finished turn, and one more each time a failed summary is tried again, spaced by the waits above: never more than one every 3 minutes. With claude-cli it counts against your account's usage, like any claude -p. With anthropic-api it is billed to the key.
| Command | What it does |
|---|---|
hopper-hq up |
Starts the daemon in the background unless it is running, then opens the building like ui . Use--no-open to print the link only. |
hopper-hq down |
Stops the daemon. |
hopper-hq start |
Runs the daemon in the foreground: collector, file watcher and local API. One daemon runs per data directory. |
hopper-hq status |
Prints a summary. Use --format text ,tmux orjson . |
hopper-hq ls |
Lists floors and their sessions. |
hopper-hq ack |
Marks finished sessions as seen. |
hopper-hq ui |
Opens the building in your browser, signed in through a one-time link. Use --no-open to print the link only. |
hopper-hq summaries |
Turns the one-line summaries on oroff , or prints how they stand (status ). SeeSummaries . |
hopper-hq demo |
Runs a daemon with synthetic sessions, and prints a sign-in link for its building. With --showcase , it plays once a longer scenario of twelve sessions on one floor, for about two minutes after a twenty-second lead. |
There are two sources of data: the mod, and Claude Code's own files under ~/.claude. Both feed one collector. The collector serves a localhost API.
Workflow runs come from both: the mod reports their agents as they start and finish, and the files give each run's name, phases and end.
The files under ~/.claude are internal to Claude Code and can change between versions. hopper-hq reads them defensively and never writes there. The mod uses Claude Code's plugin API, which is in early access.
- hopper-hq listens on 127.0.0.1 only.
- The CLI and the mod authenticate with a token stored in
~/.hopper-hq/token(mode 600). Browsers sign in with a one-time link: seeSigning in . - There is no telemetry. Nothing leaves your machine unless you turn summaries on: each summary then sends one session's notes to the provider you chose.
npm test
npm run typecheck
npm run build
npm run test:mod
npm run test:e2e
npm run build writes the CLI and the daemon to dist/ and the browser UI to dist/ui/.
npm run test:mod needs the claude CLI. It is not run in CI.
To try it with synthetic sessions, run hopper-hq demo (or node dist/bin.js demo). Then run hopper-hq ls --data-dir ~/.hopper-hq/demo. The demo replays a one-minute script. On its checkout floor, two workflow runs take turns, one starting before the other ends, so a meeting room is always open; five more sessions come and go, so the floor holds nine for a while and grows a block in the first minute; one of them rests in the lounge while it is idle. A desk has two interns, and the summary lines are fixed.
The UI is a Svelte app in ui/, with a three.js renderer for the floors in ui/renderer/. To work on it with live reload, run a demo daemon on a spare port with a throwaway data directory, then the dev server:
npm run build
node dist/bin.js demo --port 17338 --data-dir "$(mktemp -d)"
SHQ_DAEMON=http://127.0.0.1:17338 npm run dev:ui
The dev server listens on 127.0.0.1:17173 and forwards /api and /ui/login to the daemon. Open the sign-in link the demo printed, with its port changed to 17173.
npm run test:e2e builds the package and tests it in a real browser. It starts its own demo daemon on a free port between 17000 and 17999, with a temporary data directory. Then it signs in through the demo's link and walks the building, a floor in 3D, a desk, and a meeting room with its run's phases and its session's summary line, in headless Chrome, with ?motion=off. With walking on, it then waits for a robot to step out of the elevator and reach its desk. It fails on any console error or content-policy violation. Its output goes to a temporary directory that is removed after a passing run and kept after a failing one, so the screenshot and error context stay for debugging.
It runs on the Google Chrome installed on your machine and never downloads a browser. Without Chrome it stops with a message saying so. It is not part of npm test and does not run in CI.
hopper-hq is named after Grace Hopper, the computer scientist and rear admiral who popularised the word "bug" after a moth was found in a relay of the Harvard Mark II. It is not affiliated with her estate or with any other product called Hopper.
hopper-hq is provided by FairMind and is not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic.
Apache-2.0. hopper-hq is provided by FairMind; see NOTICE.
The browser UI bundles the Archivo, IBM Plex Sans and IBM Plex Mono typefaces, under the SIL Open Font License 1.1, and the Svelte, clsx and three.js libraries, under the MIT licence: see THIRD_PARTY_NOTICES.md.