airoom

A control room for your Claude Code agents.

You run Claude Code in five terminals. One is waiting for a yes, one hit a hook error twenty minutes ago, three are fine, and the one that needs you is the one you are not looking at. airoom puts all of them on one screen: every project is a room, every session is a desk, and the monitor on the desk says who is working, who is waiting on you and who is stuck. Click a desk to read what that agent is doing and answer it without leaving the app.

Everything stays on your machine. airoom reads the transcripts Claude Code already writes to ~/.claude/projects, drives agents through the Claude Agent SDK with your own login, and binds to 127.0.0.1 only. It sends no telemetry. Apart from Claude's own traffic to Anthropic, its only outbound request is a version check against airoom.dev/release.json.

Get it

macOS on Apple Silicon	airoom.dev/download, signed and notarised
Windows 11 x64, beta	airoom.dev/download?os=windows, not yet code-signed, so SmartScreen warns once per build
From source	below

Every installer is also on the Releases page.

airoom needs Claude Code installed and logged in. It drives the claude on your machine, on your account and your limits.

What it does

• One office for every project. Each project with Claude Code sessions is a room; each session is a desk. Green monitor: working. Amber: finished a turn and waiting on you. Red: blocked by a hook or a refused permission. Dark: idle. The queue in the dock lists what needs you; ⌘K (Ctrl+K on Windows) jumps to any room, desk or action.
• Chat with any agent where it sits. Click a desk for its live activity feed and a composer. A message resumes that exact session in its project directory. Interrupt a run with one click.
• Approvals, one tool call at a time. Without the bypass toggle every tool call pauses with the exact command and Allow / Deny buttons; undecided requests deny themselves after ten minutes. Bypass is per run, for repositories you trust the agent in.
• Hire. An empty desk in any room starts a brand-new session with your first message. Hire a whole team with three questions (the goal, where they work, when they check in): a lead and a crew that work tasks in parallel, each in its own git worktree, with an optional token saver. Teams are parked, not killed, when you quit.
• Knows when to interrupt you. The menu-bar or tray badge says how many agents need you, and native notifications open the right desk. An agent waiting for you stays at its desk with a marker, so a glance is enough.
• Yours to arrange. Recolour rooms, choose which projects become rooms, add decor. Preferences live in ~/.airoom/.

Run from source

Node 20 or newer (CI uses 22), and Claude Code logged in.

npm run install:all      # server, web and desktop dependencies
npm run dev              # server on :8787 and the Vite UI on :5173
npm run app              # the desktop shell against a fresh web build

npm run dist:unsigned packages a macOS app for your own machine. The signed release path is in PACKAGING.md, the Windows build in WINDOWS.md and the route to a signed Windows installer in WINDOWS-SIGNING.md.

How it works

┌──────────────┐   DataSource     ┌──────────────┐   WS / JSON   ┌──────────────┐
│ ~/.claude/   │  (interface)     │  server       │   protocol   │  web          │
│  projects/   │◀──LocalClaude────│  parse→model  │◀────────────▶│  pixel office │
└──────────────┘   DataSource     │  broadcast    │              │  (canvas)     │
                                  └──────────────┘              └──────────────┘

The server tails each session's JSONL transcript and flattens it into the model in shared/types.ts, which is also the WebSocket protocol the web client speaks. Two seams keep the local-only design swappable: DataSource (read: where sessions come from) and AgentController (write: how an agent is driven). Both have local implementations today; a hub for several machines would be remote implementations of the same two interfaces, with the protocol and the client unchanged.

Messaging (the write path)

The engine is the Claude Agent SDK, driven in streaming-input mode from the server (server/src/agent/SdkClaudeController.ts). Every send resumes the clicked desk's session in its room's working directory, which is what gives airoom interrupts, per-tool approvals and message-level streaming without process cold starts. The SDK still writes the transcript to ~/.claude/projects, so the file watcher animates the desk exactly as it does for a session started in a terminal. AIROOM_ENGINE=cli falls back to spawning the CLI per message, with no interrupts and no interactive approvals.

Things worth knowing:

• --resume <id> keeps the session id and appends to the same transcript, so a desk's identity is stable across airoom messages.
• /compact can rewrite a session file in place; the parser keys its cache on size and mtime and never assumes append-only.
• Subagent transcripts live in <project>/<sessionId>/subagents/ and are not desks.
• A desk is an active session from the last seven days; the most recent session of each project is always kept, so every project keeps its room. Claude Code itself deletes transcripts after about thirty days.
• Don't double-drive a session: avoid messaging a session that is also open in an interactive claude elsewhere; two processes on one session conflict.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗