atrium — Docs
docs/quickstart.md

Quickstart

Install an adapter and launch your first agent.

This walks through the shortest path from a fresh install to a running agent.

1. First run

There is no setup wizard. The first launch drops you into calibration — three steps inside the real app:

  1. Open a project. Bind a directory on disk. Any directory works; git repositories get extra features (branch-aware file tree, the source control pane).
  2. Connect a tool. atrium scans your PATH for the agent CLIs it knows about. Found tools install as adapters in one click. Each adapter writes files under ~/.atrium/adapters/<name>/ and injects a skill file into the tool's own skills directory (e.g. ~/.claude/skills/atrium/skill.md) so the tool knows how to use the atrium CLI.
  3. Launch your first agent.
See First run. To add an adapter later, open Settings → Tools.

2. Launch an agent

Every fresh pane opens with the launcher — a composer, not a menu.

  1. Type what you want done.
  2. Pick who does it from Talking to… (the vendor menu, whose submenus also carry launch profiles).
  3. Optionally set model and effort, a session to resume, or a worktree to isolate the work in — the chips under the composer.
  4. Choose the surface: an agent chat pane for a structured transcript, or a terminal pane for the tool's own TUI.
  5. Press Enter.
Tool calls, permission prompts, and status changes surface in the Activity sidebar regardless of which surface you picked.

3. Split and arrange

  • Cmd+D splits the focused pane right.
  • Cmd+Shift+D splits it down.
  • Drag a pane header to another split zone to move it. Dragging onto another pane's header creates a subtab group.
  • Cmd+T opens a new room. Cmd+Ctrl+N creates a new project.
Every layout change is journaled. Quit atrium and open it again — rooms, panes, scrollback, and running agents come back.

4. Resume after a crash or reboot

Closing the window doesn't stop your agents — a background daemon keeps them running, and Cmd+Q asks whether you meant detach or quit.

For everything else, atrium uses a write-ahead journal plus periodic project snapshots. When it reopens:

  • Pane layouts, scrollback, and working directories restore from the last snapshot.
  • Agents still running in the daemon are adopted — re-subscribed, not relaunched.
  • Agents with a stored session ID are resumed via the adapter's own resume path.
  • Agents whose session could not be found show a "resume failed" state with a retry.
See Persistence & recovery for the full model.

5. Drive atrium from the CLI

Inside any atrium pane, ATRIUM_CLI_PATH points at the installed CLI. Outside atrium, add ~/.atrium/bin to your PATH or call the binary directly.

# List all panes
"$ATRIUM_CLI_PATH" pane list

# Read the last 100 lines of a pane
"$ATRIUM_CLI_PATH" pane read <pane-id> --lines 100

# Open a file in a new editor pane
"$ATRIUM_CLI_PATH" path/to/file.ts

# Create a new task
"$ATRIUM_CLI_PATH" task create --title "Refactor auth" --source "user:me"

See the CLI reference for every subcommand.

Next