Agents & adapters

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

Adapter

Wraps

Chat transport

Claude Code	claude	claude-sdk
Codex	codex	codex-app-server
Antigravity	antigravity	terminal only
cursor-agent	cursor-agent	acp
Grok	grok	acp
Kimi	kimi	acp
opencode	opencode	acp
Hermes	hermes	acp
omp	omp	acp
pi	pi	pi-rpc

All ship from the atrium-adapters registry. See Adapters → Overview for installation, Building an adapter for the manifest spec, and Agent chat for what each transport can do.

Antigravity is Google's successor to the Gemini CLI; the standalone Gemini adapter it replaced is no longer shipped.

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 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.