atrium — Docs
docs/concepts/agents.md

Agents: how atrium runs CLI AI coding tools

atrium runs installed AI coding tools through adapters, in chat or terminal panes. Covers the injected environment, session resume, and coordination.

An agent in atrium is a running CLI AI tool. atrium does not reimplement the agent — it runs the vendor's real CLI (claude, codex, grok, …) and adds three layers around it:

  1. An adapter — a small bundle (manifest + optional scripts) that tells atrium how to launch the CLI, detect a session, resume a session, and handle lifecycle hooks.
  2. A pane — either a terminal pane hosting the process in a real PTY, or an agent chat pane driving the tool over its structured protocol. Both capture activity and expose the pane to the atrium CLI.
  3. A skill file — a canonical runbook written to the tool's own skills directory so the agent knows how to call atrium CLI commands from inside atrium.

Installed adapters today

Adapters ship from the atrium-adapters registry. Settings → Tools shows what is installed on each location, its version, and available updates. See Adapters → Overview for the current catalog and installation, Building an adapter for the manifest spec, and Agent chat for transport capabilities.

Starting an agent

Type what you want in the launcher, pick who does it, press Enter. Under the hood, atrium:

  1. Calls the adapter's binaryDiscovery to resolve the CLI's full path (checking $PATH and well-known install locations for nvm, fnm, volta, Homebrew).
  2. Resolves the launch surface — chat or terminal.
  3. Composes a launch command from the launch section of the manifest, applying the effective launch profile.
  4. Spawns it in the pane's PTY with the environment contract below, or opens the session over the chat transport.

The environment contract

Every atrium pane gets these environment variables injected into its shell:

  • ATRIUM — set to 1; lets any script detect "I'm running inside atrium".
  • ATRIUM_CLI_PATH — absolute path to ~/.atrium/bin/atrium. Agents should always call this instead of assuming atrium is on $PATH.
  • ATRIUM_DATA_DIR — the absolute path of the data directory (~/.atrium/ for the stable channel, ~/.atrium-dev* for dev builds).
  • ATRIUM_SOCKET — the control socket this instance listens on. Together with ATRIUM_DATA_DIR this is what makes a pane talk to the instance that spawned it, rather than whichever instance a channel name happens to resolve to.
  • ATRIUM_PANE_ID — the UUID of the current pane.
  • ATRIUM_WORKSPACE_ID, ATRIUM_TAB_ID — the project and room the pane lives in. (These keep the old vocabulary: WORKSPACE means project, TAB means room.)
  • ATRIUM_HOOK_PORT — the TCP port of the hook server (used internally by the adapter's hooks).
  • ATRIUM_TASK_ID, ATRIUM_TASK_RUN_ID — present only when the pane was launched via task dispatch.

Resuming an agent

When atrium starts, every pane that was running an agent goes through:

  1. Look up the last session ID from the pane's snapshot.
  2. Resume it. Terminal panes call the adapter's resume flag (the manifest's launch.resumeFlag) with that session ID; chat panes resume over their transport's native resume instead of shelling out.
  3. Replay — scrollback into the restored PTY, or transcript history into the chat pane, so what you see matches what you left.
If resume succeeds the pane marks itself resuming → succeeded. If the adapter reports no matching session, the pane marks itself resuming → failed and the activity card offers a retry or a fresh start.

Sessions still alive in the daemon are adopted rather than relaunched.

Stopping an agent

  • Stop (SIGTERM) — from the activity sidebar's stop button. Gives the agent a chance to clean up. The pane stays open.
  • Close (SIGKILL + teardown) — Cmd+W or the activity sidebar's close action. Kills the process and removes the pane.
  • Send to background — detach a running agent from its room so it keeps working without holding a tile. See Activity sidebar → Background agents.
If a process exits non-zero or is signal-killed, the pane captures the command and process name into a "surfaced" slot so the activity sidebar can offer a Replay action.

How agents coordinate

Agents inside atrium talk to each other through atrium agent message. Messages are recorded and displayed in the receiving conversation or terminal. To find agents on every paired machine, use atrium agent list --all-locations, then address a remote agent as <id>@<location>. See Agent messaging.

Reusable skills and named agents

Skills (SKILL.md runbooks) and named agent definitions (saved adapter + system prompt + attached skills) live in a sidebar registry that any agent can pull from at submit time using +skill and ++agent shorthand. A named agent is distinct from a launch profile, which saves model, effort, permissions, and launch options. See Skills & agents for the registry and Sigils & auto-injection for how the shorthand expands into context.