Launching agents

The composer-first launcher, hotkey chains, and the CLI.

A fresh pane opens with the launcher: a hero composer where you type what you want done, pick who does it, and press Enter. The old grid of adapter tiles is gone — the adapter is now one chip among several on a single composer, so the prompt is the thing you start with.

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

The hero composer

A rotating heading above the composer. Greetings are drawn from an evergreen bank plus contextual banks gated on time of day, weekday, calendar date, project name, adapter, theme, room count, and your achievement stats. Everything is computed synchronously at mount, so the heading never swaps after paint.
An identity row — the adapter picker on the left ("Talking to…"), the chat/terminal surface toggle on the right.
A footer chip row — profile, tune, permission, session, and worktree.
A pane dock, demoted below the composer, for turning the pane into something other than an agent.

Type and press Enter to launch with your message as the first prompt. Launch with an empty composer to start the agent with no message at all. The composer keeps leading /, !, and # keystrokes rather than swallowing them, so slash commands and shell-style prefixes survive into the session.

The launcher uses a container-query collapse ladder keyed to the pane, so it stays usable as the pane narrows rather than hiding itself.

The adapter picker

Click Talking to… to open the vendor menu. Each detected adapter row hosts a submenu of its launch profiles, with the Default marked and a summary line, plus New profile:

Click the adapter row alone → that adapter with its Default profile.
Click a profile in the submenu → adapter and bound profile in one gesture.

A Manage adapters item at the foot of the menu opens Settings → Tools. Adapters whose binary atrium cannot find are disabled here; the same screen is where you point atrium at a custom path.

The chips

Chip	What it sets

Profile	The bound launch profile. Also reachable from the vendor submenu.
Tune	Model and reasoning effort. Effort is a discrete slider snapped to the stops that adapter actually exposes.
Permission	Sandboxed vs. skip-checks, for adapters that expose permission modes.
Session	Resume a recent session for this adapter + directory, or start fresh.
Worktree	Launch into a new git worktree, with the branch name derived from your prompt. Clicking a disarmed chip both arms it and opens its popover; the switch inside the popover disarms it again.

Selections are per pane. Two side-by-side launchers keep independent state, and nothing you pick here changes another pane's defaults.

An account chip appears for adapters with multiple signed-in accounts — see Accounts & quota.

Attaching files

Drag files onto the launcher to attach them as chips, or use the composer's + menu to add files or a QA capture. Typing @ opens the universal reference finder — files, skills, agents, run commands, and launch profiles. See Sigils.

Pane dock

Below the composer sits the pane dock, for when you want this pane to be something other than an agent: Terminal (T), Browser (B), Search (F), Git (G), Tasks (K), Task (J), Notepad (N). Each carries a chord-and-hold hotkey badge.

Hotkey chains

Two ways to trigger a tile's hotkey letter:

Double-shift hold. Tap Shift once to arm, hold Shift again to activate. Hotkey letters overlay every tile; with shift held, tap a letter.
Cmd-hold chain. Hold Cmd, press T (new room), D (split right), or Shift+D (split down), keep Cmd held, then tap a launcher letter. The new pane's launcher activates with the hotkey buffer and dispatches as soon as it mounts.

Sequence

Result

`Cmd+T G`	New room → git panel
`Cmd+T N`	New room → notepad
`Cmd+T C`	New room → launch Claude Code
`Cmd+D C`	Split right → launch Claude Code
`Cmd+Shift+D X`	Split down → launch Codex
`Cmd+T W`	Closes the just-created pane (while Cmd is still held)

The chain routes through atrium's shortcut layer, so it works even for keys with macOS menu roles. System edit shortcuts (Cmd+C, Cmd+V, Cmd+A) pass through untouched, so copy / paste / select-all in a focused text input still work while Cmd is held.

Pane-dock letters are reserved: T, B, F, G, K, J, N. Adapters whose natural initial collides get an override — Codex → X.

Binary detection

On first launch and whenever you install an adapter, atrium scans $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, so tools installed via npm i -g usually appear without configuration.

An adapter lands in one of three states:

Detected — binary found, --version returned a non-empty string. Ready to launch.
Broken command (amber) — binary is on $PATH but --version returned empty, typically a shadowed alias or wrapper script. The version slot becomes a fix command link that opens an inline editor for the real path.
Missing — not found anywhere. The adapter still installs; its row is disabled until you provide a command.

All three states surface identically in Settings → Tools, which is also where you set the order adapters appear in and manage adapter updates.

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 — with friendly per-adapter names.
Reasoning effort — filtered to the efforts that model actually offers.
Permission mode — sandboxed vs. skip-checks.
Surface — chat or terminal.
CLI flags — with per-adapter suggestions as you type.
Environment variables — layered on top of the per-adapter env.
An optional agent — bind a ++slug so its prompt and skills inject at SessionStart.

Apply one from the vendor submenu, the profile chip, the full Launch Profile editor (create, rename, duplicate, edit, set an adapter's Default), or the CLI. Each adapter has one Default that applies whenever you launch without picking another — including CLI launches via pane create --adapter.

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

From the CLI

# 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

# Inspect the adapter's model aliases and launcher options
"$ATRIUM_CLI_PATH" adapter show claude-code

# Create an Opus profile and make it the Claude Code Default
"$ATRIUM_CLI_PATH" launch-profile create \
    --adapter claude-code --name "Opus orchestrator" \
    --model opus --effort high --permission-mode strict --default

# Launch an agent definition through that exact profile
"$ATRIUM_CLI_PATH" launch <agent-slug> \
    --adapter claude-code --profile opus-orchestrator --surface chat

# Create a pane with a specific launch profile
"$ATRIUM_CLI_PATH" pane create --type terminal \
    --adapter claude-code --profile opus-orchestrator

Create, inspect, edit, promote, and delete profiles. The first profile created for an adapter becomes its persisted Default; --default and set-default select a different Default explicitly. --permission-mode updates terminal and chat permission state together. The lower-level --permission KEY=BOOL form is for adapter-declared boolean launcher toggles and rejects unknown keys.

"$ATRIUM_CLI_PATH" launch-profile list [--adapter <name>]
"$ATRIUM_CLI_PATH" launch-profile show <slug> [--adapter <name>]
"$ATRIUM_CLI_PATH" launch-profile create \
    --adapter <name> --name <name> [--slug <slug>] \
    [--model <alias-or-id>] [--effort <level>] \
    [--permission-mode strict|plan|auto|yolo] [--default]
"$ATRIUM_CLI_PATH" launch-profile edit <slug> [--adapter <name>] \
    [--model <alias-or-id>] [--permission-mode strict|plan|auto|yolo]
"$ATRIUM_CLI_PATH" launch-profile set-default <slug> [--adapter <name>]
"$ATRIUM_CLI_PATH" launch-profile delete <slug> [--adapter <name>]

Manage agent definitions:

"$ATRIUM_CLI_PATH" agent definition list
"$ATRIUM_CLI_PATH" agent definition create <slug> --prompt <file>
"$ATRIUM_CLI_PATH" agent definition delete <slug>

What happens on launch

atrium resolves the adapter's binary via the manifest's binaryDiscovery block.
It resolves the launch surface — chat or terminal.
It composes the launch from the launch block plus the effective profile.
Terminal: the command spawns in the pane's PTY with the environment contract. Chat: the session starts over the adapter's chat transport.
The session-start hook fires so the Activity sidebar picks it up and resume can later find the conversation.