Agent Office

A pixel-art office that visualizes your Claude Code agents in real time.

Quick start

npx @imnephy/agent-office install

That's it. claude runs in any project will now show up in the office. Open http://localhost:39001 to watch.

⚠️ Global hooks — install adds entries to ~/.claude/settings.json that fire on every claude session, including private/work projects. Tool inputs (file paths, Bash commands, search patterns) are broadcast to the local bridge and logged to ~/.agent-office/bridge.log (mode 0600).

Before working in a sensitive repo, run agent-office stop — hooks still fire but harmlessly fail on connection refused (and Claude Code doesn't notice). Use agent-office uninstall for full removal.

Commands

npx @imnephy/agent-office install          # start + wire hooks + open browser
npx @imnephy/agent-office status           # show running state, port, hook state
npx @imnephy/agent-office stop
npx @imnephy/agent-office restart
npx @imnephy/agent-office uninstall        # stop + remove hooks
npx @imnephy/agent-office logs --follow

Flags

--port <n>        # custom port (default 39001, or $AGENT_OFFICE_PORT)
--url <u>         # custom hook URL (tunnel / VPS)
--no-open         # skip opening the browser
--no-hooks        # start without modifying ~/.claude/settings.json

How it works

Everything lives on one HTTP port (default 39001):

  GET  /              → static UI
  POST /hook          → Claude Code hook events
  GET  /ws            → WebSocket (agent state broadcasts)
  GET  /health        → JSON status

The CLI writes a detached bridge PID to ~/.agent-office/bridge.pid and its log to ~/.agent-office/bridge.log. install also merges two entries (PreToolUse / PostToolUse) into ~/.claude/settings.json that POST each hook payload to /hook. Uninstall reverses both — preserving any other hooks you've configured.

Deploying to VPS / self-hosted

A Dockerfile and docker-compose.yml ship in this repo for VPS / self-hosted deployments where you want long-running containers behind a tunnel.

docker compose up -d
./scripts/install-hooks.sh --url https://your-domain.example/hook

The built UI auto-detects its WebSocket endpoint from window.location (same origin, /ws path), so no rebuild is needed when you serve it behind a reverse proxy — just make sure both /hook and /ws pass through.

./install.sh is a convenience wrapper around docker compose for the VPS flow; see ./install.sh --help.

Development

pnpm install
pnpm dev                    # Vite dev server (UI from source)
pnpm build                  # tsc + vite build
node server/bridge.mjs      # run bridge directly

Because the built UI uses same-origin auto-detection, the Vite dev server needs to be told where the bridge lives. Set VITE_WS_URL before pnpm dev:

VITE_WS_URL=ws://localhost:39001/ws pnpm dev

See CLAUDE.md for codebase details.