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

Claude Code	`claude`	`#d97706`
Codex	`codex`	`#059669`
Gemini	`gemini`	`#4285f4`

All three require app version ≥ 0.65.0 and target macOS.

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.

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
Gemini → its 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 workspace-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.