atriumatrium

Agents & adapters

What agents are, how adapters plug them in.

An agent in atrium is a running CLI AI tool inside a terminal pane. atrium does not reimplement the agent — it runs the vendor's real CLI (for example, claude, codex, gemini) in a real PTY 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 — a terminal pane that hosts the agent process, captures output for the Activity sidebar, and exposes 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

  • Claude Code — wraps the claude binary. Accent orange.
  • Codex — wraps the codex binary. Accent green.
  • Gemini — wraps the gemini binary. Accent blue.
All three are shipped from the atrium-adapters registry. See Adapters → Overview for installation and Adapters → Building an adapter for the manifest spec.

Starting an agent

The simplest flow is the in-pane launcher:

  1. Open an empty terminal pane.
  2. Click an adapter tile in the launcher bar.
  3. 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. Composes a launch command from the launch section of the manifest, applying any launcher options you chose.
  3. Spawns the command in the pane's PTY with the environment contract (see below).

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 data directory (~/.atrium/ for Early Access, ~/.atrium-dev/ for dev builds).
  • ATRIUM_PANE_ID — the UUID of the current pane.
  • ATRIUM_WORKSPACE_ID, ATRIUM_TAB_ID — the workspace and room the pane lives in.
  • 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. Call the adapter's resume flag (from the manifest's launch.resumeFlag) with that session ID.
  3. Replay scrollback into the restored PTY so the visible terminal matches what you last saw.
If resume succeeds the pane marks itself resuming → succeeded. If the adapter reports no matching session, the pane marks itself resuming → failed and shows a Nudge button in the activity card to retry or start fresh.

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.
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 the atrium agent message CLI command. See Agent messaging for the framing protocol. This is the only sanctioned inter-agent channel — it uses the CLI so both parties see it in their terminal history.

Reusable skills and named agents

Skills (SKILL.md runbooks) and named agent profiles (saved adapter + system prompt + attached skills) live in a workspace-sidebar registry that any agent can pull from at submit time using +skill and ++agent shorthand. See Skills & agents for the registry mental model and Sigils & auto-injection for how the shorthand expands into real context.