backroom / docs / agents & orchestration

Agents & orchestration

An agent is a configured Claude Code session with a home: a name, a brief, a working directory, a room, and a security posture. Orchestration is everything that lets many of them behave like one staff.

What an agent is

Each agent is a JSON file: which room it belongs to, what it is for, where it works, whether it runs bare or in a container, which projects it may read or write, and which MCP servers it may call. Its transcript, its widgets, and its notes are files beside it. Because a turn is a fresh process built from that config, editing the file changes the agent's next turn with no restart.

Agents are not chat personas. A code-room agent has a real checkout and runs real builds; a finance agent reads real exports. The brief tells it what it owns, and the widget protocol tells it how to show its work.

Routing the one chat

Chat is a single thread for the whole app. Each message is routed to exactly one agent:

• @mention an agent to address it directly.
• Otherwise a small, fast classifier model reads the message against every agent's name and brief and picks the best fit.

The reply streams back into the shared thread labelled with the agent that produced it, and the full exchange also lands in that agent's own channel, so context is never split between the two views. A digest of the routed conversation keeps each agent aware of what the others have been asked lately.

Agents using agents

Backroom exposes itself to its own agents as an MCP surface: an agent can list its peers with their briefs, read another room's dashboard, and hand a task to a specific agent. That makes cross-domain questions one tool call instead of a human relaying answers between rooms, and it is the mechanism a coordinator agent builds on.

Shared memory

Agents share an index plus a directory of notes, not one growing log:

shared/MEMORY.md                 index, one line per note, hard-capped
shared/notes/<agent>/<topic>.md  the finding itself, read on demand

Only the index is injected into prompts. Each line carries a trigger sentence saying when the note is worth opening, which lets a model choose without reading everything. Writes are structural rather than hopeful: a consolidation pass runs after substantial turns and asks what another agent would otherwise rediscover, because prompting a mid-task agent to "remember things" reliably produces nothing. The cap is enforced in code; past it, nothing would ever be read anyway.

There is deliberately no vector index. On a realistic corpus, plain lexical search beat every locally computable embedding by roughly two to one, and the cold "months ago, nobody knows what to grep for" case is answered better by a cheap model reading the curated index than by cosine similarity.

Learned guidance

When you correct an agent, the correction can be kept as a standing rule that rides its future prompts: the agent equivalent of "we talked about this". Guidance is per-agent, visible on disk, and editable like everything else.

Scheduling

Agents can run on schedules for briefs, sweeps, and housekeeping. Scheduled turns run headless, which constrains them honestly: a headless turn can never answer a permission prompt, so scheduled agents run with pre-authorised edit permissions and explicitly allowlisted tools, and anything that would stall asking for approval is a configuration bug surfaced, not a hang tolerated.

Scheduling fires only while the app is open and the Mac is awake. A running turn holds off idle sleep; a closed lid stops the world. For genuinely unattended work, a system-level scheduled job calling the CLI directly is the more reliable tool, and the docs say so rather than overselling the in-app scheduler.

MCP servers, without running them as you

A published MCP server is arbitrary code, and the usual way to run one is as your user on your Mac. Backroom instead gives each managed server its own long-lived container with no project mounts and one writable state directory, then bridges its stdio to the network for agents to call.

• Grants are explicit and empty by default. Adding a server exposes it to no one until an agent is granted it, so a new server cannot silently widen what every agent can do.
• Sealed agents reach servers through the credential proxy, which re-checks the grant on every call against the turn's ticket.
• Your own terminal can join in. A per-server opt-in exposes it to the host's Claude Code through a loopback-only gateway with a derived bearer token, so the same contained Stripe or Sentry server serves both the app's agents and your shell.
• Config is rebuilt every turn, because a container's address changes when it spins down idle; a cached config would point at a dead VM.

Containing a server protects your Mac from the code. It cannot protect the data you hand the server, and security states that boundary plainly.

Some providers host their MCP server themselves, as an https endpoint and an API key rather than a package: nothing to download, nothing to contain. Backroom wires one of those straight to a single agent. The key is kept in the Mac's Keychain and injected into the connection each turn, so it never sits in the agent's config file on disk.