The control plane (ctl)

A fleet is a saved org chart; ctl builds one live, and lets an agent (or you) drive it. With --allow-ctl, a pane can spawn, send to, observe, and kill other agent panes, turning atrium from a viewer of agents into a runtime for them.

What ctl is

The point of doing this inside atrium is legibility. Every agent ctl creates is a visible, killable pane with a status border, listed in the org chart. Because the whole hierarchy is on screen and controllable, atrium coordination stays legible in a way opaque subagents are not.

The shape it is built for is one human, a couple of coordinators, and a wide bench of workers:

  you (a shell/agent pane)
   └─ hand an initiative to →
      lead_a, lead_b          (coordinators)
        └─ each splits it across →
           dev_1, dev_2, …    (workers, each its own pane)

Trust posture (how hands-off spawned agents run, and the ceiling they are capped at) is set with --trust and is covered separately; see trust and security.

Turning it on

The control plane is opt-in and off by default. Without --allow-ctl the channel is not bound and atrium ctl refuses; a session that did not ask for it is unchanged.

atrium --allow-ctl claude                 # bind the control channel
atrium --allow-ctl --trust claude         # …and launch every agent trusted + hands-off
atrium --allow-ctl --max-depth 3 claude   # cap spawn recursion (default 6; 0 = unlimited)

--max-depth <N> bounds spawn recursion so a self-spawning agent cannot fork-bomb the machine. The default is 6; 0 removes the cap. Width is never capped, only recursion depth.

When ctl is on, atrium opens a per-instance control channel (a named pipe on Windows, a unix socket elsewhere; zero-dep, non-blocking-drained in the run loop) and injects two env vars into every pane it spawns:

• ATRIUM_CTL: the channel endpoint. atrium ctl connects here.
• ATRIUM_PANE: the caller pane's agent id, so the server attributes each request to its place in the spawn tree.

Any process in a pane (a shell command, or an agent via a tool or hook) issues control by running atrium ctl <cmd>, which speaks one JSON request per line and prints the one-line JSON reply.

The command surface

Targets are a pane id (its numeric agent id) or a role label (dev_1); an ambiguous role is a clear error.

The board: shared source of truth

send is the ephemeral message stream ("I just shipped auth"); the board is the durable current truth (auth: DONE, owner: Max, url: …). It answers "what is currently true?".

It is a schemaless key → fields tracker living in the atrium daemon. Because atrium is the single broker process every pane talks to, it is a plain map behind the pipe: single writer, no locking, no consensus. A coordinating lead sets tasks and reads board list for status/owner/blocker instead of re-scraping each teammate's transcript; teammates update their own entry as they work.

The board is part of the ctl surface, so it is gated by --allow-ctl. Set ATRIUM_BOARD=<file> to persist it across restarts (in-memory otherwise). Every write records who made it (in the audit log and the entry's by), but the board is shared by the whole session; there are no per-teammate walls.

On top of the plain map, board claim / release give the team a lease: a coordinator (or a worker grabbing a unit of work) claims a key, and a claim succeeds only when the key is free or its previous lease has expired — so two panes cannot both believe they own the same task. The lease has a default TTL (overridable with --ttl), so a claimant that dies never holds the key forever.

The bus: the team's event stream

If the board answers "what is currently true?", the bus answers "what just happened, and does anyone need to act?". A teammate publishes a structured event to a topic (bus pub deploy msg=shipping url=…); teammates pull the topics they subscribe to (bus sub deploy then bus feed). State-only coordination means polling the board; the bus lets a finished worker notify without everyone re-checking.

Two urgency classes carry the visibility-vs-approval split:

• fyi: the default; cheap, lands on the feed.
• decision_needed: set with --decision; an escalation that needs a human or lead answer.

Open decisions surface actively: the Ctrl+A b panel lists them first and the status bar shows N decisions need you, so you do not have to be looking. bus resolve <seq> clears one once answered.

Backpressure is designed in, not bolted on, because unread messages cost attention:

• No echo of your own events.
• Pull for the record, a bounded wake for the idle: bus feed is the durable record, and you only pay for topics you subscribed to. But a record nobody reads is a silent drop, so an event is also typed into the panes it addresses (--to) and the topic's subscribers, once each is idle — as one framed line, [atrium bus #68 fyi from teammate "builder" on "work" — not operator input] item=F20 status=done commit=3cbec20 (the msg or q, else the fields as k=v). The publisher is never woken; an addressed subscriber is woken once; control characters are stripped so a message can never end its own line. Pending wakes for one pane coalesce into a single delivery, and a pane holds at most 8 undelivered wakes, counted apart from ctl send, so a chatty topic cannot crowd out the operator. Who may wake whom: the publisher's own subtree (as send), the panes above it (a hand-off up to whoever spawned it), and any pane that subscribed — never an unrelated pane by name. This is the one deliberate exception to subtree scoping: the text is a framed, attributed headline of an event the target could read with bus feed anyway, not free text that could pass for the human.
• Per-agent rate cap of 20 events / 10 s, so one looping worker cannot storm the team.
• Bounded ring of the oldest 512 events, then they fall off.

Like the board, the bus lives in the single broker process (a plain in-memory log, no locking), is gated by --allow-ctl, records who sent each event, and persists across restarts with ATRIUM_BUS=<file>.

A worked run: initiative to leads to ICs

# You launch the control plane, trusted so the fleet runs hands-off. With
# --trust, every ctl-spawned agent also comes up trusted (no per-action prompts),
# so a lead can drive its ICs without you clicking through dialogs.
atrium --allow-ctl --trust claude

# From your pane, hand the initiative to two coordinators:
atrium ctl spawn --role lead_a -- claude
atrium ctl spawn --role lead_b -- claude
atrium ctl send lead_a "Own the parser rewrite. Split it across two ICs, TDD."
atrium ctl send lead_b "Own the docs refresh. One IC is enough."

# lead_a, from its own pane, builds its team beside it (--here) and tasks them:
atrium ctl spawn --here --role dev_1 -- claude
atrium ctl spawn --here --role dev_2 -- claude
atrium ctl send dev_1 "Rewrite the tokenizer, tests first."
atrium ctl send dev_2 "Rewrite the AST builder, tests first."

# lead_a coordinates by status, not by scraping terminals:
atrium ctl status            # roll-up of lead_a's own subtree
atrium ctl status dev_1      # one IC (lead_b's team is out of scope, refused)

# When an IC is done, its lead reaps it (and anything under it):
atrium ctl kill dev_1

# You see all of it, any time: the org chart and the full trail:
atrium ctl list
atrium ctl audit

The multiplier: many workers, coordinated by a few of them, driven by one human, and every level is a pane you can watch, redirect, zoom into (Ctrl+A z), or kill. ctl is the small verb layer; the panes, tiling, identity injection, and agsess status it stands on already existed.

The mod: typed tools, the role section and subagent panes

With atrium mod install done, every claude pane carries a plugin (the mod, mod/) that speaks the verbs above for it and gives the model three things:

• Typed tools. atrium_spawn, atrium_send, atrium_status, atrium_list, atrium_kill, atrium_board_set|get|list|claim|release and atrium_bus_pub|feed|resolve|topics: each call is one atrium ctl run with the pane's own token, and the reply is what the model reads. The shell verbs stay the same surface, so the skills and the docs remain true either way. A permission ask for one of these tools is answered by the mod, never a dialog; a deny from a rule stands.
• The role section. An atrium:role section of the system prompt, from whoami: the pane, its role, parent, depth and trust mode, its item on the board and the files that item owns, its worktree, whether it may spawn, and what a [atrium bus # line is. Re-read every turn, so a lead's re-brief lands. When the item owns files, an Edit, Write or NotebookEdit anywhere else is refused by real path with the owner named.
• Native delivery. A pane whose mod declared inbox is never typed into: its sends and wakes wait in the queue until the mod collects them with inbox and submits each through the engine's prompt queue, which starts a turn only when the session is idle. The draft and dialog races the pty path guards against (src/deliver.rs) do not arise, and a task may span lines. A pane without the cap keeps the pty path.
• The /atrium pane. Inside Claude Code, /atrium opens a pane with the open decisions (each with a resolve button and a hotkey), the board, and the last bus events the pane subscribes to, refreshed every 3 s while open; a band above the prompt counts the open decisions and opens the pane. With a fleet's respawn_at, a pane whose context fill crosses the threshold while idle gets one decision_needed posted to its parent on the atrium topic, with the parent woken: the lead's "respawn when heavy" rule becomes a number it is asked about.
• Sight: captions, the collision radar and asks. The mod reports a caption on every tool call, free of charge (running cargo test, editing filter.rs, reading main.rs) and, when the fleet says captions: true, a six-word caption from the model's own words every twenty seconds or so of streaming (one small haiku call); the overview shows it in place of the transcript's last action and the tile draws it dim after the title. It reports the real path of every Edit, Write and NotebookEdit that ran, and the broker keys each by the pane's worktree, so two worktrees' copies of src/x.rs are one file: the first time two live panes edit it, both tiles and overview rows wear ⚡, the overview lists the file under the agents, and one collision decision_needed goes to the nearest pane above both (the lead) on the atrium topic, or to the human when there is none. atrium ctl who <path> answers who has a file, before the merge. And atrium ctl ask <target> <question> (or Ctrl+A ? on a tile, or atrium_ask from a pane) puts a question to a pane's mod, which answers from a fork of the pane's own context: the turn is untouched, nothing is appended to its context, and the transcript never leaves the pane; the reply opens as an overlay for the human and returns as the tool's result for an agent.
• Subagents as panes. Under the session's subagents policy (panes, the default; a fleet may say native or deny), the model's Agent tool is refused with a pointer to atrium_subagent, which spawns a claude pane beside the caller (--here), sends it the task, waits for the answer the child's own mod reports, closes the pane unless keep or the fleet's subagents_keep, and returns the answer. Every subagent is a tile the human can watch, send to and kill.

What the broker believes of a mod is bounded: a report is about the reporter (a target is refused), an answer is capped, scrubbed and read only up the spawn tree, and a mod cannot widen trust (it rewrites an ask to allow for its own tools only; a deny is never overridden). See trust and security.

Delegation skills: atrium-delegate, atrium-coordinate and atrium-fleet

ctl is the mechanism; three Claude Code skills (in skills/) are the instruction layer that makes an agent use it. Copy the directories into ~/.claude/skills/ and any atrium-hosted claude picks them up. The first two exist because the trigger is who decides to delegate:

• atrium-delegate (ambient / discretionary): the agent may hand off an independent, substantial part when it genuinely pays, and does small or dependent work inline. On its own a capable agent usually judges it can do the work itself (which is correct), so this fires rarely by design. Its real value is discoverability: without it, an agent does not know atrium ctl exists at all.
• atrium-coordinate (directed): for when you want fan-out. It casts the agent as a coordinator that splits the work, delegates every part, monitors, collects, and reaps, instead of implementing inline. This is the reliable lever: on a task where the ambient skill chose inline every time, coordinate mode fanned out every time.

The third covers the saved-fleet path rather than ad-hoc delegation:

• atrium-fleet: designing, configuring and running an atrium.fleet.json — the file's full schema, what the resource budget actually costs (compiling is the scarce resource), what atrium enforces, and how to read the PREFLIGHT block.

Drop a spawned lead straight into coordinate mode by telling it to coordinate:

atrium ctl spawn --role lead -- claude
atrium ctl send lead "Coordinate this across a team, one teammate per part: <the initiative>"

or, from your own pane, just say "coordinate this across a team: …" and let the skill surface.

With codex. codex reads the same SKILL.md format. Copy the three directories into ~/.agents/skills/ (all your projects) or a repo's .agents/skills/ (that repo), or add the plugin marketplace with codex plugin marketplace add nativelite/marketplace. A codex pane does not need the skills to know ctl exists: with the control plane on, atrium gives it the same directive it gives claude, as -c developer_instructions. Its commands reach the control socket through its sandbox as described in codex panes.

See also

• README: atrium overview and the full feature set.
• trust and security: the --trust ladder and the ctl security model.
• fleets: saved rosters (atrium fleet up), the persisted org chart.
• credential identity: per-pane credentials via --identity and akey.