Adapters overview

The registry, installation flow, and what an adapter is.

An adapter is the thing atrium uses to launch and resume a specific CLI AI tool. Adapters are shipped from the atrium-adapters repository, not bundled into the atrium app itself. This decouples the adapter ecosystem from app releases — new and updated adapters ship without an atrium update.

Official adapters

Adapter

Binary

Accent

Chat transport

Claude Code	`claude`	`#d97757`	`claude-sdk`
Codex	`codex`	`#059669`	`codex-app-server`
Antigravity	`agy`	`#14b8a6`	terminal only
Cursor Agent	`cursor-agent`	`#6366f1`	`acp`
Grok	`grok`	`#e11d48`	`acp`
Kimi	`kimi`	`#4f6bff`	`acp`
OpenCode	`opencode`	`#a855f7`	`acp`
Hermes	`hermes`	`#e0a32e`	`acp`
omp	`omp`	`#f97316`	`acp`
Pi	`pi`	`#06b6d4`	`pi-rpc`

All target macOS. Each declares its own minAppVersion; atrium won't offer an adapter that needs a newer app than you're running.

The chat transport column is what lets an adapter run in an agent chat pane rather than only a terminal. Antigravity — Google's successor to the Gemini CLI, which replaced the standalone gemini adapter — is terminal-only for now.

What an adapter contains

An adapter directory (both in the registry and under ~/.atrium/adapters/<name>/ after install) contains at minimum:

~/.atrium/adapters/claude-code/
├── adapter.json          ← the manifest
├── hooks.sh              ← install/uninstall/status hook
└── launcher_options.json ← optional: extra launcher UI

Advanced adapters may add:

Additional shell scripts referenced by the manifest's methods map.
Static JSON files referenced as { "static": "path.json" } method sources.

See Building an adapter for the full manifest spec.

The registry

atrium fetches the list of available adapters from the registry:

Production and Early Access builds — GitHub Contents API against jonnyasmar/atrium-adapters, cached for one hour.
Dev builds — if the sibling directory ../atrium-adapters/adapters/<name>/ exists next to the atrium source tree, it is used in place of the remote fetch. This is how developers iterate on adapters locally.

Installing an adapter

UI: Settings → Tools. Each available adapter shows an Install / Uninstall button, a version stamp, an inline editable command field with verify, and up/down buttons to reorder the adapter grid in the launcher. Hovering an adapter pill in the launcher reveals two quick-action buttons — reinstall from local (useful when iterating on an adapter you are building) and pull latest from GitHub.

Under the hood:

atrium creates a temp directory ~/.atrium/adapters/.installing-<name>.
Every file in the registry's adapter directory is downloaded recursively. .sh scripts get 0755.
The manifest schema is validated. All scripts referenced by the methods map must exist.
The temp directory is renamed to ~/.atrium/adapters/<name>/ — an atomic swap.
atrium reloads its adapter registry and:

- Installs the canonical skill file (see below) to the adapter's declared skillInstallPath. - Runs hooks.sh install to give the adapter a chance to wire up its own hooks.

The UI reflects the new list.

Updates

There are two independent things to keep current: the adapter (atrium's integration) and the harness (the vendor's CLI binary itself).

Adapter updates

Because adapters ship from the registry independently of the app, atrium keeps them current for you:

Auto-update — installed adapters update to the latest compatible version automatically. Toggle it under Settings → Updates (on by default).
Update notice — when installed adapters fall behind, a notice surfaces with a one-click Update all that refreshes them in place, no atrium restart required.

"Compatible" respects each adapter's minAppVersion gate, so an adapter that needs a newer atrium won't be pulled until you update the app.

Harness updates

atrium also periodically probes each adapter's check_update method for a newer version of the underlying CLI. When one is available, an accent chip appears beside Talking to <adapter> in the launcher, with both versions in its tooltip. Click it and atrium runs the adapter's updateCommand in a visible terminal pane, then re-probes.

atrium also suppresses each harness's own self-updater for sessions it spawns. A CLI that swaps its own binary out from under a live session is a good way to corrupt a running conversation; your launch profile environment still wins if you set the variable yourself.

Canonical assets

The canonical atrium skill, context file, and bundled skills refresh on the same periodic cadence rather than only at app launch, driven by a manifest in the adapters repo and gated on content hash. A long-running atrium picks up shipped content updates for the next agent session without a restart.

Uninstalling

Settings → Tools → Uninstall, or programmatically via atrium adapter CLI (coming). Uninstall:

Runs hooks.sh uninstall (best-effort, 5-second timeout).
Deletes ~/.atrium/adapters/<name>/.
Removes the injected skill file at skillInstallPath.
Reloads the registry.

The canonical skill

The file at atrium-adapters/skills/atrium/SKILL.md is the agent's runbook for using atrium's CLI from inside a pane. On install, atrium copies it to each adapter's declared skillInstallPath:

Claude Code → ~/.claude/skills/atrium/skill.md
Codex → ~/.codex/skills/atrium/SKILL.md
Every other adapter → its own tool-native skill location

The skill is authored once and propagated. To update it, edit the canonical file in the adapters repo; adapters using it will pick up the new version on the next install. Do not hand-edit files under ~/.claude/skills/atrium/ etc. — they are regenerated.

The canonical adapter skill is one entry in a larger project-wide registry: skills you author, harness-installed skills, and the vercel-labs/skills catalog all surface in the Skills & Agents sidebar mode together. See Skills & agents for the registry and Sigils & auto-injection for the +skill / ++agent shorthand any agent can use to pull from it.

Hooks

Adapters declare hook points in the manifest's hooks object — event name → atrium://hooks/<adapter>/<event> URI. At install time, hooks.sh install wires the tool's own hook system (for example, Claude Code's hook registration) to call atrium on each event.

Fired events include:

session-start / session-end
pre-tool-use / post-tool-use
stop / stop-failure
notification
user-prompt-submit
permission-request
task-created / task-completed
subagent-start / subagent-stop

These are what drive the activity sidebar's status transitions and the task dispatch machinery.

Performance rules

Adapter scripts run synchronously in the app's startup and installation paths. Hard rules:

Scripts must complete in under 50 ms in the common case. No per-file subprocess loops, no network calls.
The registry initialization is synchronous in the app's setup() — do not move it to a background thread.

Failing scripts are skipped with a warning rather than crashing the app, but a slow script will visibly delay launch.