Adapters: connect Claude Code, Codex, and more
The adapter registry, official tools, chat transports, installation and repair, fleet updates, and the hooks that drive activity status.
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 | acp |
| Cursor Agent | cursor-agent | #6366f1 | acp |
| Grok | grok | #e11d48 | acp |
| Kimi Code | kimi | #4f6bff | acp |
| OpenCode | opencode | #a855f7 | acp |
| Hermes | hermes | #e0a32e | acp |
| Oh My Pi | omp | #f97316 | acp |
| Pi | pi | #06b6d4 | pi-rpc |
| Muse Code | muse | #0064e0 | muse-msp |
| Goose | goose | #f59e0b | acp |
Each declares its own minAppVersion; atrium won't offer an adapter that needs a newer app than you're running. On an SSH location, availability also depends on whether that adapter's underlying CLI supports the box's Linux architecture.
The chat transport column is what lets an adapter run in an agent chat pane. Antigravity uses a separate ACP server that atrium manages alongside its terminal CLI. Availability and features depend on the installed adapter, runtime, and operating system; the launcher shows failures and repair actions when a tool is not ready.
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
methodsmap. - Static JSON files referenced as
{ "static": "path.json" }method sources.
The registry
atrium fetches the list of available adapters from the registry:
- Released builds, including the public beta — 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 adapter shows its installation state, version, command path, and setup checklist. The checklist distinguishes the tool binary, hooks, and status reporting, so an installed binary with failed hooks does not read as fully ready. Use Repair to retry missing setup; a failure shows the affected step and its reason. atrium bundles jq on macOS and Windows for adapter scripts that need it.
Under the hood:
- atrium creates a temp directory
~/.atrium/adapters/.installing-<name>. - Every file in the registry's adapter directory is downloaded recursively.
.shscripts get0755. - The manifest schema is validated. All scripts referenced by the
methodsmap must exist. - The temp directory is renamed to
~/.atrium/adapters/<name>/— an atomic swap. - atrium reloads its adapter registry.
- It installs the canonical skill file (see below) to the adapter's declared
skillInstallPathand runshooks.sh installso the adapter can 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.
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.
Settings → Tools also shows tool versions across connected locations. Fleet updates report each machine's outcome, including an offline location or a failed command; a remote tool update runs on that machine.
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 removes the adapter's integration. 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
~/.claude/skills/atrium/ etc. — locally changed files can be withheld from automatic replacement, leaving that copy behind the published version.
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-endpre-tool-use/post-tool-usestop/stop-failurenotificationuser-prompt-submitpermission-requesttask-created/task-completedsubagent-start/subagent-stop
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.