Set Up Agent Office and Manage AI Coding Workers in a Shared 3D Workspace

What Agent Office Does

Agent Office turns AI-assisted software development into a shared cartoon 3D office. Each GitHub repository becomes a separate floor containing desks, coding workers, terminals, issue and pull request boards, a task queue, services, and project-specific settings.

You can seat a Claude Code, OpenCode, or Codex worker at a desk, watch its live terminal on the desk laptop, and open the same terminal with teammates. Workers can operate in the main checkout or in isolated Git worktrees, making it possible to run multiple tasks in parallel without sharing a working directory.

The application also provides multiplayer movement, voice, screen sharing, persistent chat and terminal history, worker notifications, machine monitoring, project navigation, GitHub issue and pull request workflows, and structured multi-agent meetings.

Key Concepts

One floor per repository

The first time Agent Office starts, it opens in the elevator and asks you to select a repository visible to your authenticated GitHub CLI account. You can also enter a repository as owner/name.

The repository is cloned into:

~/agent-office/<owner>/<repo>

Each project floor has independent workers, desks, boards, queues, services, pictures, and colors. People on one floor only see and hear others on that floor.

Workers at desks

An empty desk can host Claude Code, OpenCode, Codex, or a shared login shell. An occupied desk displays the worker's live terminal and status. Agent hooks or plugins report whether the worker is working, waiting for input, or done.

GitHub boards and task automation

The issues board organizes issues into open, in-progress, and closed groups. The pull request board displays drafts, reviews, approvals, merges, closures, CI state, and diff size. Tasks can be handed directly to workers or added to the persistent queue for automatic execution.

Prerequisites and Installation

The provided README describes how to operate Agent Office but does not include a package-manager installation command. Install the project using the repository's distribution or build instructions, then make sure the agent-office executable is available in your shell.

Before starting, authenticate the GitHub CLI account that the server should use:

gh auth status

If authentication is missing, complete the GitHub CLI login flow:

gh auth login

The selected account determines which repositories Agent Office can discover and which identity is used for GitHub actions such as posting issue comments.

You should also have at least one supported coding-agent CLI configured on the machine if you intend to hire that type of worker. Agent Office supports Claude Code, OpenCode, and Codex workers.

Start Your First Office

Launch the application with:

agent-office

1. Open the Agent Office interface in your browser using the address shown by the application.
2. Use the elevator's project selector to choose a repository available through gh, or type its full owner/name.
3. Wait while Agent Office clones the repository under ~/agent-office.
4. Choose your character's skin tone, hairstyle, hair color, and shirt.
5. Enter the new project floor.

To add or visit another project later, walk into the elevator on the north wall and press E. You can also click the project name in the upper-left corner and select another floor.

Optional launch configuration

The README documents several useful server options. For example:

agent-office --city Berlin --max-workers 4

The --city Berlin option makes sunrise, sunset, and weather follow Berlin. The --max-workers 4 option places a server-wide limit on simultaneously running workers across all floors. Shared shells and board agents also count toward this limit.

Team notifications can be connected to a Slack or Discord incoming webhook:

agent-office --webhook <incoming-webhook-url>

Budget warnings and hiring pauses are available through --budget and --budget-pause. These controls use tracked Claude Code spending only. They cannot directly cap OpenCode or Codex spending, although reaching the tracked hiring threshold pauses all new workers.

Learn the Basic Controls

• WASD: Walk around the floor.
• Space: Jump.
• Mouse drag: Orbit the camera.
• E: Interact with desks, boards, elevators, seats, ladders, and other office objects.
• Tab: Open the main menu.
• T: Read recent chat lines.
• P: Write a task before hiring at an empty desk.
• B: Open a shared login shell at an empty desk.
• C: Inspect changes at an occupied desk.
• N: Visit the worker that has been waiting longest.
• R: Resume a supported worker session that exited.
• /: Search chat and worker terminal history.

The main menu opens windows for workers, people, issues, pull requests, the queue, services, search, voice, screen sharing, settings, and other status panels. Frequently used items can be pinned to the top bar, and browser-specific layout choices are retained.

Hire Your First Coding Worker

1. Walk to an empty desk.
2. Press E.
3. Select Claude Code, OpenCode, or Codex.
4. Enter the task you want the worker to complete.
5. If appropriate, enable own git worktree.
6. Confirm the hire and watch the worker's terminal appear on the laptop.

You can press P at an empty desk when you want to compose the task before choosing the agent. Agent Office provides 16 desks. If they are occupied, temporary bean-bag workstations can accommodate up to 12 additional workers.

Use isolated worktrees for parallel tasks

Enable own git worktree when multiple workers may edit the repository at the same time. Agent Office creates an office/<name> branch and places its checkout under:

.agent-office/worktrees/

This keeps parallel workers from modifying the same checkout. When sending a worktree worker home, you can keep the branch and worktree, delete only the worktree, or delete both. Agent Office warns about uncommitted changes and commits that have not reached a remote.

To clean up retained worktrees once it is safe, run:

agent-office prune

Open and Collaborate in a Worker Terminal

Press E at an occupied desk to open its real PTY terminal over WebSockets. Multiple teammates can type into the session simultaneously, and late arrivals receive the existing scrollback.

The terminal header shows who currently has the terminal open. It also displays a typing notice when another person is entering text, reducing the chance that collaborators overwrite one another's input.

Worker terminals and their last 3,000 lines are saved. Agent processes run separately from the main server, so workers can continue through a server reload or process restart. Open terminals reconnect automatically when the server returns.

Understand live worker status

A worker's antenna and animation indicate its state. Workers may appear as working, needs input, or done. Their animations also reflect actions such as reading files, editing code, running tests, searching the web, or encountering repeated failures.

When a worker needs help or completes its task, Agent Office plays a notification and makes the worker visible in the waiting count. Press N to move to the oldest waiting worker. Repeatedly pressing N cycles through the waiting workers.

Review Changes and Open a Pull Request

At an occupied desk, press C or select Changes from the terminal. The changes view shows modified files and a continuously refreshed diff against the branch on which the office was opened.

From this view, you can:

• Inspect changed files and their diffs.
• Commit the worker's changes.
• Discard unwanted changes.
• Push the branch.
• Open a pull request.

For a worker using an isolated worktree, press O at the desk when the work is ready. Agent Office pushes the branch and opens a pull request with a title and description drafted from the task. Work originating from a GitHub issue includes a Closes #n reference. Press O again to view the pull request.

Work with GitHub Issues

The issues board shows open, in-progress, and closed issues. Select an issue to read its description and comments, post a comment, send it to a worker, or add it to the task queue.

You can also physically pick up an issue card:

1. Point at the issue note and press E, or use Pick it up in the issue window.
2. Carry the card to an empty desk to hire a new worker.
3. Carry it to an occupied desk to hand it to that worker.
4. Carry it to the task queue to enqueue it.
5. Press Q if you want to return the card to the board.

When a worker receives an issue card, Agent Office assigns that issue through GitHub, moving it into the in-progress state. Issues can also be closed as completed or not planned, with an optional comment.

Review and Merge Pull Requests

The PR board groups pull requests into draft, in-review, approved, merged, and closed states. It also reports CI status and diff size.

Open a pull request and select Files changed to inspect its diff. Files can be displayed as a folder tree or a flat list. Review comments appear under their associated lines.

• Press V to mark a file as reviewed.
• Use J and K to move between files.
• Choose Review to hand the PR to a worker.
• Choose Fix comments & merge to have a worker address feedback, make checks pass, and merge.
• If the branch conflicts with its base, use Fix conflicts & merge.

Agent Office can squash, merge, or rebase a pull request. It can also ask GitHub to merge automatically after required checks pass. When a pull request merges, the office rings its merge gong, releases confetti, and animates active workers.

Automate Work with the Task Queue

The task queue is available from the whiteboard on the north wall or from the main menu. Add a free-text task or queue an issue, then let Agent Office assign the work automatically.

When a desk is available and the queue's concurrency setting allows another worker, the next task receives a fresh worker in an isolated Git worktree. The default queue concurrency is three workers. Setting workers at once to zero pauses the queue.

Queued issue work is assigned on GitHub, and the resulting pull request is linked on the queue board when it appears. Completed workers remain at their desks for inspection until the queue needs the seat for another task. Queue state survives restarts.

Use Specialized Board Agents

The issues board, PR board, and task queue each have a kiosk agent. Walk to a kiosk and press E to give it a prompt.

• Issues agent: Finds, files, triages, labels, and closes issues through gh.
• PR agent: Summarizes, reviews, comments on, and merges pull requests.
• Queue agent: Converts a request into one or more queued tasks, reports queue status, and removes tasks.

The queue agent does not implement code changes itself. It creates queue tasks so that fresh workers can perform the work in isolated worktrees. Press O at a kiosk to inspect its terminal or X to send the agent home.

Run Structured Multi-Agent Meetings

The meeting room supports groups of two to five workers. Start a meeting from the room, the main menu, an issue, or a pull request. Each participant has a role that you can rename.

Available patterns include:

• Debate: Workers propose approaches, critique one another, and produce a final decision.
• Lead & team: A lead divides the task, delegates parts, and combines the results.
• Map-reduce: Mappers process separate files, modules, issues, or other parts before one worker combines the findings.
• Red / blue: Red-team workers identify bugs, security risks, and edge cases while blue-team workers address valid findings.
• Review panel: Reviewers examine a pull request through different lenses before a lead combines and posts the review.

Every meeting declares an output file and runs on its own branch. When the output is ready, use Open PR to create a pull request. Meetings have round limits and a table-wide token budget, preventing them from continuing indefinitely.

Monitor Services, Resources, and Spending

Development services

When a worker launches a web server such as npm run dev, a preview build, or python -m http.server, it appears on the Services board within a few seconds. Each entry identifies the worker, branch, and page title. Selecting it copies a command for opening that server from your own computer.

Machine pressure and worker limits

The west-wall monitor shows current CPU and memory usage, five-minute histories, and the number of running workers. If memory reaches 90 percent, or CPU stays 90 percent busy for roughly half a minute, Agent Office warns that the machine is under pressure.

A server-level --max-workers value provides a hard ceiling. An administrator can lower the active limit in settings but cannot raise it beyond the startup value. When capacity is full, manual hires are rejected with an explanation, while queued tasks wait for an opening.

Usage and cost reporting

Claude Code workers report tracked session cost and tokens. OpenCode reports tokens and model/provider estimates, including child sessions when available. Codex reports recorded root-session tokens, including cache and reasoning breakdowns, but not cost or API-call count.

Enable Claude limits from the menu to display Claude plan usage for the five-hour session, weekly allowance, and any model-specific weekly limit. This panel is hidden when Claude uses an API key rather than a plan, and it does not include OpenCode or Codex.

Advanced Collaboration Tips

• Use worktrees by default for concurrent coding: This prevents workers from sharing uncommitted files or changing one another's branches.
• Separate planning from implementation: Use issue and queue agents to organize work, then let fresh worktree workers make code changes.
• Keep queue concurrency below the machine limit: Leave capacity for interactive workers, shared shells, and board agents.
• Use desktop notifications: They can take you directly to a worker that needs input or has finished while the office tab is in the background.
• Configure team webhooks: Slack or Discord notifications help the team notice workers that have remained unattended.
• Search before reopening sessions: Press / to search chat and all retained terminal output, including history from before a restart.
• Use a shared shell for support work: Press B at an empty desk when you need a collaborative terminal for tests, Git commands, or development servers without hiring an AI worker.
• Inspect before sending workers home: Review terminal history and changes, then decide whether to preserve or remove the worker's branch and worktree.

Conclusion

Agent Office combines AI coding agents, Git worktrees, shared terminals, GitHub boards, queues, notifications, and multiplayer collaboration in one spatial interface. Start with a single project floor and one isolated worker, then introduce queued tasks, board agents, pull request workflows, and structured meetings as your team becomes comfortable with parallel AI-assisted development.