Hopper HQ: An office building where Claude agents gets a desk

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

Install

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.

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:

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:

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:

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.

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.

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.

Signing in

The daemon listens on 127.0.0.1 only.

hopper-hq ui asks 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/token and 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, Go and Go to pane are simulated: the page says which pane it would switch to, and tmux is never touched.

tmux

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.

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>]:

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.

Each summary sends a fixed instruction and these notes about one session, each cut to one line:

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.

--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 i