atrium — Docs
docs/quickstart.md

Quickstart: launch your first AI coding agent

Install atrium, connect Claude Code or Codex, and get an agent running in a pane in under five minutes — the shortest path from download to first task.

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.

6. Optional: add another machine

Open Settings → Locations → New location, enter the address of a Linux box you can reach over SSH, and follow the connection check. atrium sets up a key, pairs the box, and provisions its daemon. A password or sudo password entered during setup is used for that connection only; atrium does not store it.

Once connected, choose Run on in the launcher to start work there. The project, rooms, panes, agents, task cards, notes, and source-control tools remain in the same macOS UI, while commands and files stay on the selected box. See Locations for project copies, reconnect behavior, and trust boundaries.

Next