atriumatrium

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

On first launch, atrium runs an onboarding wizard:

  1. Pick a workspace directory. Any directory works; git repositories get extra features (branch-aware file tree, the source control pane).
  2. Detect installed tools. atrium scans your PATH for claude, codex, and gemini. Tools that are found can be installed as adapters in one click.
  3. Install adapters. Each installed adapter writes a small set of 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.
  4. Pick a theme and telemetry preference.
If you skip the wizard or want to add an adapter later, open Settings → Tools and install it from the registry.

2. Launch an agent

Open an empty terminal pane. The launcher bar sits at the top of empty panes and shows an adapter picker.

  1. Click an adapter (e.g. Claude Code).
  2. Optionally pick a recent session from the dropdown — atrium reads the adapter's own session store and offers to resume.
  3. Optionally add CLI args or toggle YOLO mode (skip atrium's output capture).
  4. Press Enter.
The pane now runs the adapter's CLI. Type prompts directly into the terminal. Tool calls, permission prompts, and status changes surface in the Activity sidebar.

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 (tab). Cmd+Shift+N creates a new workspace.
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

atrium uses a write-ahead journal plus periodic workspace snapshots. When it reopens:

  • Pane layouts, scrollback, and working directories restore from the last snapshot.
  • Agents with a detected session ID are resumed automatically via the adapter's resume command.
  • Agents whose session could not be found show a "resume failed" state with a Nudge button to 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