atriumatrium

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

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

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.

If a binary is missing, the adapter still installs — the launcher tile is disabled until you provide a custom command in Settings → Tools.

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.

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

What happens on launch

Regardless of entry point, atrium:

  1. Resolves the adapter's binary via the binaryDiscovery block in the manifest (checks $PATH, then the adapter's well-known paths).
  2. Composes a launch command from the launch block, applying any launcher option values you chose.
  3. 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).
  4. Fires the adapter's session-start hook so the Activity sidebar picks it up and session resume can later find the conversation.