✨ A look around

The office, live. Each character is a real agent in your session.	Poke a character and it bobs and pops a bubble with its current status. It never moves or changes state.
End-of-day card. One click exports the day as a PNG. A quiet day says so.	繁體中文 built in. Labels, bubbles, and names all localized.

Meet the Team

Office Life

Leave it running and stuff just… happens. Some events fire on real signals from your session —
a real deploy sets off the celebration, a blocked streak kicks off the argument — while the social
stuff drifts in on a timer and quietly backs off when a live session is busy, so the office never
talks over real work:

• Tea Break — a few sneak off to the coffee machine to talk about the others
• Stand-up — PM herds everyone to the whiteboard. Nobody escapes.
• Food's Here — someone walks in with a bag. Productivity ends.
• Review Beef — Dev: "no bug." QA: "look here." Dev: "…fine."
• It Deployed — Ops slaps the button, the whole room loses it
• Eureka — Architect freezes, then sprints to the whiteboard

…and the rare stuff: someone brings a dog, the AC dies and everyone fans themselves, the boss does a
walkthrough and the whole office suddenly looks very busy.

The office fills the width of whatever you dock it in — IDE sidebar, half-screen, full window — with no
dead gutters. Hit ☰ for a vertical roster: who's working, who's blocked, and a live feed of what just happened.

Why it's nice

It's pure SVG — 8 hand-drawn characters, no canvas, no GPU, tiny bundle.

The same tool animates differently per role. qa + Bash pulls out a magnifier; ops + Bash hits the deploy button; designer + Edit walks to the whiteboard.

Everything you see is real. Events fire from your actual session, and an agent's status is never made up. When one gets stuck you see why — 🧪 test run, 🔨 build, 📦 install, or just ❔ unknown — with a ↻ when the same thing keeps failing. It only names a cause when the hook actually reports one; otherwise it stays vague on purpose.

Each role murmurs in its own voice — the skeptic QA, the brisk PM, the heads-down Researcher — but the speech bubble is only for that voice; status always rides the colored ring and a work symbol. Personality without faking it: no invented conversations, no made-up rapport the agents couldn't actually have.

Click a character and it bobs and tells you what it's doing right now. It won't move or change state. Space pokes again; right-click pokes without opening the inspector.

One click saves the day as a little pixel-art postcard you can share. Slow day with nothing finished? The card says so.

The quieter stuff: weather follows the room's mood, 45 seconds of silence reads as thinking instead of stuck, reduced-motion and a11y are respected, and a watchdog keeps anyone from freezing mid-walk.

→ The classifier, movement, and behavior engine are written up in docs/ARCHITECTURE.md.

Quick Start

# Straight from the public GitHub repo — no clone, no install:
npx github:KbWen/agent-virtual-office

# Using Claude Code? Wire up automatic status in one command:
npx github:KbWen/agent-virtual-office setup

Open the browser tab it pops, and your agents are already at their desks. That's it — no backend, no
database, no WebSocket.

git clone https://github.com/KbWen/agent-virtual-office.git
cd agent-virtual-office
npm install
npm run dev

CLI flags: --port=PORT · --lang=en|zh-TW · --no-open · --no-host (localhost only; the dev
server otherwise binds all interfaces).

The dev server has no authentication and exposes to your LAN by default. Use --no-host for
localhost-only, or the production serve mode with an OFFICE_API_TOKEN for a secured deploy.

Hosting it for a team (production build, Docker, Nginx, PM2, TLS) → docs/deployment/DEPLOYMENT.md.

Connect Your Agent

The office reacts to any tool that can send an HTTP request:

# Tell the office an agent is working:
curl -X POST http://localhost:5174/api/status \
  -H "Content-Type: application/json" \
  -d '{"dev":"working","workflow":"Sprint 42"}'

# Or fire a one-shot CI moment:
curl -X POST http://localhost:5174/api/event -d '{"event":"deploy-success"}'

• Claude Code → npx agent-virtual-office setup, and every tool call routes itself. Done.
• Codex CLI / Codex App / Gemini CLI / GitHub Actions / any CI → see the Integration guide.

Hook events registered by setup

Opt-in capture mode (AVO-153)

The hook supports capturing raw hook events for fixture generation and schema validation:

1. Enable: touch ~/.claude/office-hook-capture (Linux/macOS) or New-Item ~/.claude/office-hook-capture (PowerShell)
2. Use Claude Code normally — every tool call appends a JSON line to ~/.claude/office-hook-capture.jsonl
3. Sanitize: node scripts/sanitize-hook-capture.mjs → creates tests/fixtures/hook-events/*.json
4. Review: check fixtures for residual sensitive strings before committing
5. Disable: remove the marker file; raw capture stays in ~/.claude (never committed)

The capture path is fully try/catch'd — enabling or disabling it has zero effect on normal hook behavior.

Embedding & language

http://localhost:5174?mode=panel     # compact panel for IDE sidebars
http://localhost:5174?lang=zh-TW     # force Traditional Chinese

English is the default; Traditional Chinese is available via ?lang=zh-TW, the in-app EN/中 toggle,
the --lang flag, or browser auto-detect (zh-TW / zh-Hant).

Name & recolor your agents

Make the roster yours — rename the characters (and optionally recolor them) to match your real team
or your own naming. Two ways, both override the existing roles (pm, arch, dev, qa, ops,
res, gate, designer):

# URL param — rename by role (name:role, comma-separated):
http://localhost:5174?agents=Alice:dev,Bob:qa,Chen:pm

// Before the app loads (e.g. an inline <script> in a custom host page) — rename AND recolor:
window.__office_config__ = {
  agents: {
    dev: { name: 'Alice', color: '#E8927C' },
    qa:  { name: 'Bob',   color: '#7CA7E8' },
  },
}

The ?agents= URL param sets names only; window.__office_config__ sets names + colors. This
changes who the existing characters are, not their pixel-art looks — custom sprite art (hats,
outfits, per-agent accessories) is a separate, not-yet-built track (see docs/SPRITE_REQUIREMENTS.md).

Diagnostics & soak testing

Visual/emergent bugs (stacked characters, teleports, frozen walkers) live in minutes of
runtime, not in any single function — so the repo ships its own observation tools:

All three reuse a running npm run dev server on :5173, or start their own. If you see a
visual glitch, run the matching recorder before theorizing — every overlap/rhythm fix in
v1.4.0 started from one of these captures.

Troubleshooting

Office is blank — no agents appear

1. No hooks installed? Run npx agent-virtual-office setup.
2. Wrong directory? The office only shows sessions from the directory you launched it in — run it from
   your project root, or point it somewhere else with OFFICE_PROJECT_ROOT=/path/to/project.
3. Stale status? Status expires after 5 minutes of inactivity — start a new session.
4. Not using Claude Code? Push status with curl (see Connect Your Agent).

Port 5174 in use → npx agent-virtual-office --port=5175

Browser doesn't open (headless Linux / WSL / remote) → open http://localhost:5174 manually.

Colleagues can't see it (LAN) → set OFFICE_API_ALLOWED_ORIGINS=http://192.168.1.100:5174, or use --no-host for localhost only.

Windows Firewall prompt → the dev server binds all interfaces; use --no-host to avoid it.

Node version error → requires Node ≥ 22 (node --version).

Strict CSP — animations missing → allow style-src 'self' 'unsafe-inline' (the exception applies to
style= attributes only). The office still works without it — only the weather/movement decoration drops.
Full notes in docs/ARCHITECTURE.md.

FAQ

What is Agent Virtual Office?

Agent Virtual Office is an open-source, pixel-art visualization of AI coding agents. It turns a live
Claude Code, Codex, or Gemini CLI session into a tiny office where each agent is a character that
visibly works, gets blocked, and ships — in real time, driven only by real signals from your session.
Built with React and pure SVG, it runs entirely on your machine with no backend.

How do I visualize Claude Code activity?

Run npx github:KbWen/agent-virtual-office setup once. It registers Claude Code hooks so every tool
call, subagent, and turn updates the office automatically — no manual wiring, no API keys.

Does it work with Codex, Gemini CLI, or CI pipelines?

Yes. Anything that can send an HTTP POST can drive the office — Codex CLI / Codex App, Gemini CLI,
GitHub Actions, or your own scripts. See the Integration guide.

Is it a dashboard or a token/cost tracker?

No. It doesn't chart tokens, spend, or productivity. It's an honest visualization: an agent's status
only updates when a real signal comes in, and activity is never faked. It's a desk toy, not a metrics tool.

Does it send my code or data anywhere?

No. There is no backend, no database, no telemetry, and no external service. Status updates travel
over HTTP on your own machine — localhost by default, with optional LAN exposure you can turn off
via --no-host.

Do I need to install anything?

No. npx github:KbWen/agent-virtual-office runs it straight from the public GitHub repo. The only
requirement is Node.js ≥ 22.

Tech stack

React 19 + Vite 8 · SVG · Zustand · Tailwind CSS v4 · requestAnimationFrame. Runs in the browser, no backend.
2000+ tests cover the classifier, inference, store, movement, event honesty, blocked-reason detection, poke, and the share card. Deep dive → docs/ARCHITECTURE.md.

Contributing

PRs welcome — the office can always use more life. Skim the docs for the technical lay of the
land before diving in.

License

MIT