Launching agents

The in-pane launcher, hotkey chains, and the CLI.

Agents are launched from one surface — the in-pane launcher — plus a keyboard chain that extends into new panes and a CLI surface for scripting.

The launcher

A fresh terminal pane opens with the launcher docked at the bottom. It is the primary way to start work in a pane, and it does more than pick an adapter:

A grid of adapter tiles for every installed adapter.
A pane dock for turning the pane into a Terminal, Browser, Search, Git, Tasks, or Task view in place — without going back to the toolbar.
A rotating tips row with keyboard and drag-drop hints, resolved live against your current keybindings.
Hotkey overlays that reveal a single letter on every tile, activated by a double-shift hold or a cmd-hold chain.

The launcher auto-dismisses when you launch an adapter, pick a pane type from the dock, or send your first command in the terminal. Typing while the launcher is visible stays with the terminal — it does not steal focus.

Press Cmd+L on a focused pane to bring the launcher back.

Adapter tiles

Each tile carries everything you need to launch without leaving the pane:

The adapter's brand icon and display name. Adapters can ship a canonical brand SVG via their manifest's icon field; uninstalled adapters in the registry render the same SVG so the brand stays consistent across the install / uninstall transition. See Building an adapter → icon.
A hotkey letter in the top-left (the first letter of the adapter's name, or a safe override — X for Codex, M for Gemini, because C and G are reserved for the pane dock). Revealed by the shift-hold and cmd-hold indicators.
⌘↵ in the top-right — the launch CTA. Cmd+Enter on the selected tile launches with its current settings.
A session summary line: the recent-session count and the "most recent" timestamp for this adapter + working directory. Sessions are loaded lazily — only when you open the session picker.
A session picker dropdown. Open it to filter recent sessions, pick one to resume, or leave it on "+ New session" for a fresh conversation.
An agent picker below the session picker. Click the Bot trigger to open the universal ++ autocomplete (grouped items, + Create agent action row, keyboard nav). Picking an agent binds its named profile to the pane; on launch, SessionStart delivers the agent's prompt and attached skills the same way an in-pane ++slug mention does. An external × next to the trigger clears the selection. The agent picker is per-tile — each launcher pane starts with an empty draft, so adapter state never bleeds across panes.
A launch-profile picker beside the agent row — pick a saved launch profile (model, reasoning effort, permission mode, CLI flags, environment) to apply on launch, with a quick-switch popover for hopping between profiles without reopening the editor. The picked profile is per-tile, so choosing one in this pane never changes a side-by-side pane's default.
A YOLO toggle (when the adapter declares one) shown as a 👮/🤷 switch. 👮 is sandboxed permissions, 🤷 skips permission checks.
A CLI args input with autocomplete from your past launches of this adapter.
A gear icon (bottom-right) that opens the adapter's settings dialog — per-adapter environment variables live here; see Adapter environment.

A tile is disabled when atrium cannot find the adapter's binary on your $PATH or in any of its declared fallback locations. A Missing a tool? Add manually link appears below the grid when at least one adapter is undetected; it jumps to Settings → Tools where you can point atrium at a custom binary path.

Pane dock

Alongside the adapter tiles is a pane dock with six tiles:

Terminal (T), Browser (B), Search (F), Git (G), Tasks (K), Task (J).

Clicking a pane-dock tile replaces the launcher with that pane type in the current pane. Useful when you created a pane with Cmd+D / Cmd+Shift+D and decide mid-flow you want a git panel or a browser there instead of a terminal.

Hotkey overlays

There are two ways to trigger the hotkey letter on any tile:

Double-shift hold. Tap Shift once to arm, hold Shift again to activate. The launcher overlays the hotkey letter on every tile. With shift held, tap a letter to launch that adapter or pane type.
Cmd-hold chain. Hold Cmd and press T (new room), D (split right), or Shift+D (split down); keep Cmd held; press a launcher letter. The new pane's launcher activates with the hotkey buffer and dispatches as soon as it mounts. So Cmd+T G opens a new room containing the git panel, Cmd+D C splits right and launches Claude Code, and Cmd+T W closes the just-created pane without releasing Cmd.

Rotating tips

The top row shows a single tip that rotates roughly every nine seconds. Tips cover keyboard shortcuts (with the chord resolved against your current keymap), drag-drop gestures, the CLI, speech-to-text, and pane-dock tricks. Long tips marquee-scroll just enough to reveal the tail.

Adaptive sizing

The launcher adapts to the pane's shape:

Wide panes (≥ 760 px) get the full layout.
Medium and small panes tighten columns, shrink metadata, and collapse the top strip.
When the launcher would take more than 60 % of the pane's height, it hides itself entirely — you can still open it with Cmd+L or grow the pane back to bring it back.
The active adapter tile expands inside its row, but adjacent unselected tiles stay on the same row as long as there's horizontal room — only the lone-on-its-row case promotes the active tile to full width.

First-run binary detection

On first launch and when you install a new adapter, atrium scans your $PATH and well-known install locations for each adapter's binary. It understands Node version managers (nvm, fnm, volta, asdf) and the Apple Silicon Homebrew path (/opt/homebrew/bin), so tools installed via npm i -g typically show up without manual configuration.

The first-run wizard's tools step lays out adapters in a single column up to four detected tools; past that, it switches to a 2-column grid so the catalog stays within a comfortable height as more adapters appear in the registry.

An adapter can land in three detection states:

Detected — binary found on $PATH (or one of the well-known paths), --version returned a non-empty string. Green check, ready to launch.
Broken command (amber) — binary is on $PATH but --version returned empty. Typically a shadowed alias or wrapper script. The path subtitle is amber; the version slot becomes a fix command link that drops into the inline editor so you can point atrium at the real binary. The row's checkbox unchecks itself until the issue is resolved. Saving the new path optimistically merges the verified path and version into memory instead of re-running discovery against the still-broken default.
Missing — binary not found anywhere. The adapter still installs; the launcher tile is disabled until you provide a custom command.

The amber "broken command" state also surfaces in Settings → Tools with the same affordances.

Per-adapter setup

The adapter tile's gear icon opens the adapter settings dialog, where you manage environment variables applied only to panes running that adapter. Paste a .env block into any key field and atrium expands it into rows (supports KEY=value, export KEY=value, quoted values, and # comments). See Adapter environment.

The adapter itself (its binary command, its hotkey conflicts, its default launcher options) is configured in Settings → Tools — along with the order adapters appear in the launcher grid.

Launch profiles

A launch profile is a saved, reusable launch setup — the _how_ of a launch, kept separate from the _who_ (the agent you bind). One profile bundles:

Model — shown with friendly names per adapter (for claude-code, that includes Claude Fable 5).
Reasoning effort — the effort level the adapter exposes.
Permission mode — sandboxed vs. skip-checks (the launcher's 👮/🤷 toggle).
CLI flags — per-launch arguments, with per-adapter flag suggestions surfaced as you edit.
Environment variables — applied to the pane's shell on top of the per-adapter env.
An optional agent — bind a ++slug agent so its prompt and skills inject at SessionStart.

Apply a profile three ways: from the launch-profile picker on a launcher tile (with its quick-switch popover), from the full Launch Profile editor (a manage dialog where you create, rename, duplicate, edit, and set an adapter's Default), or from the CLI. Each adapter has one Default profile that applies whenever you launch without picking another — including CLI launches via pane create --adapter.

Once a pane is running, its session footer shows a launch-profile chip naming the active profile. Last-used tracks the profile you actually launch, not the one you hover, and the selection is per-pane so two side-by-side terminals keep independent defaults.

Profiles are agent-orthogonal: a profile carries no prompt, and an agent carries no runtime knobs. Bind both and the launch ships the agent's context _through_ the profile's runtime. Named profiles persist at the app level, so they're available in every workspace.

From the CLI

For scripting or one-off headless use, the CLI launches the same flow:

Open a new pane with Claude Code launched.

"$ATRIUM_CLI_PATH" pane create \
    --type terminal \
    --adapter claude-code \
    --focus

Split the current pane and launch Codex.

"$ATRIUM_CLI_PATH" pane create \
    --type terminal \
    --adapter codex \
    --split "$ATRIUM_PANE_ID" \
    --direction horizontal \
    --focus

Launch with per-launch adapter flags.

"$ATRIUM_CLI_PATH" pane create \
    --type terminal \
    --adapter claude-code \
    --adapter-flags '{"yolo": true, "cli_args": "--thinking"}'

Drive the launcher programmatically (for example from a keybinding).

"$ATRIUM_CLI_PATH" launcher open   --pane-id "$ATRIUM_PANE_ID"
"$ATRIUM_CLI_PATH" launcher select --pane-id "$ATRIUM_PANE_ID" --adapter claude-code

Inspect or promote launch profiles. A bare pane create --adapter <name> applies that adapter's Default profile; set-default is how you change which profile that is.

"$ATRIUM_CLI_PATH" launch-profile list [<adapter>]
"$ATRIUM_CLI_PATH" launch-profile show <slug> [<adapter>]
"$ATRIUM_CLI_PATH" launch-profile set-default <slug> [<adapter>]

What happens on launch

Regardless of entry point, atrium:

Resolves the adapter's binary via the binaryDiscovery block in the manifest (checks $PATH, then the adapter's well-known paths).
Composes a launch command from the launch block, applying any launcher option values you chose.
Spawns the command in the pane's PTY with the environment contract (ATRIUM_CLI_PATH, ATRIUM_PANE_ID, ATRIUM_DATA_DIR, plus any per-adapter env vars from the gear icon).
Fires the adapter's session-start hook so the Activity sidebar picks it up and session resume can later find the conversation.