Data directory

atrium stores all user data under a single directory, keyed by build channel:

• Early Access and Stable — ~/.atrium/
• Beta — ~/.atrium-beta/
• Dev builds — ~/.atrium-dev/

The active path is exported as ATRIUM_DATA_DIR in every pane.

Layout

~/.atrium/
├── config.json                   ← user configuration
├── state.json                    ← app-level state (open workspaces, window geometry)
├── tasks.db                      ← SQLite: tasks, runs, segments, comments, labels, statuses
│
├── workspaces/
│   └── {workspace-id}/
│       ├── workspace.{ts1}.json  ← workspace snapshot (rotated)
│       ├── workspace.{ts2}.json
│       └── ...
│
├── themes/
│   └── {name}-custom.json        ← user-authored themes
│
├── adapters/
│   └── {adapter-name}/
│       ├── adapter.json
│       ├── hooks.sh
│       └── ...                   ← adapter-specific files
│
├── bin/
│   └── atrium                    ← CLI binary (re-installed on every app launch)
│
├── shell/
│   └── env.sh                    ← sourced by shells on USR1 to apply env changes
│
├── zsh/
│   ├── .zshenv
│   ├── .zprofile
│   ├── .zshrc
│   └── .zlogin                   ← zsh bootstrap (chain into user's real dotfiles)
│
├── journal/
│   └── state.{timestamp}.json    ← audit trail of state saves
│
└── diagnostics/                  ← optional; only when diagnostics are enabled
    └── trace.{timestamp}.json

config.json

User configuration. See Configuration for the schema.

• Atomic writes (temp file + rename).
• 0600 permissions.
• Hand-editable; atrium watches the file.

state.json

App-level state. Not for hand-editing.

{
  "open_workspaces": ["<workspace-id>", ...],
  "focused_workspace": "<workspace-id>",
  "window_geometry": { "x": 100, "y": 100, "width": 1600, "height": 1000 }
}

Written via a dirty-tracked heartbeat — saves only fire when something changed.

tasks.db

SQLite database holding every task card, run, segment, comment, label, and status. Workspace-scoped. Queried through the atrium task and atrium run CLI surfaces; the schema is an internal implementation detail and can change between app versions.

Safe to back up when atrium is not running.

workspaces/{id}/workspace.{timestamp}.json

Per-workspace snapshot. The core of atrium's resumability.

Rough shape:

{
  "id": "<uuid>",
  "name": "atrium",
  "project_dir": "/Users/jonnyasmar/dev/atrium",
  "is_worktree": false,
  "parent_workspace_id": null,
  "worktree_branch": null,
  "worktree_base_ref": null,

  "tabs": [
    {
      "id": "<tab-uuid>",
      "name": "main",
      "layout_tree": { ... },
      "pane_ids": ["<pane-uuid>", ...],
      "is_active": true,
      "pinned": false,
      "sub_tab_groups": [...]
    }
  ],

  "panes": {
    "<pane-uuid>": {
      "pane_type": "terminal",
      "name": "Claude Code",
      "cwd": "/Users/jonnyasmar/dev/atrium",
      "custom_title": null,
      "file_path": null,
      "adapter_type": "claude-code",
      "session_id": "abc123...",
      "scrollback": "...",
      "scrollback_format": "rust-grid",
      "last_command": "claude",
      "surfaced_command": null
    }
  }
}

Multiple timestamped snapshots are retained per workspace. atrium loads the most recent one and can fall back to the previous one if it fails to parse.

themes/

User-authored theme files, named {name}-custom.json. See Themes for the schema. atrium watches this directory and reloads themes on change.

adapters/

Installed adapter bundles. Each directory holds at minimum adapter.json and hooks.sh. See Adapters.

Seeded on app launch from the atrium-adapters registry (or the sibling directory in dev builds).

bin/atrium

The CLI binary. atrium re-installs it on every launch if the version does not match the bundled CLI. Executable (0755). The path is exported as ATRIUM_CLI_PATH into every pane.

Add ~/.atrium/bin to your shell $PATH to call atrium outside atrium.

shell/env.sh

A bash-compatible script written by atrium to carry env var changes from the app into running shells. Sourced on USR1 signal by atrium's shell integration (__atrium_apply_env).

Do not edit by hand — atrium overwrites it whenever configuration changes.

zsh/

Bootstrap dotfiles for zsh shell integration. atrium sets ZDOTDIR to this directory when launching a zsh shell. Each bootstrap file sources the user's real dotfile (via ATRIUM_REAL_ZDOTDIR) and then installs atrium's hooks.

journal/

Audit trail of state saves. Non-fatal — if writes here fail, the app continues. Use these files to inspect history or restore after catastrophic corruption of the live state.json.

Environment variables atrium sets

For every shell atrium launches:

• ATRIUM=1
• ATRIUM_CLI_PATH — absolute path to bin/atrium.
• ATRIUM_DATA_DIR — absolute path to the active data directory.
• ATRIUM_PANE_ID — pane UUID.
• ATRIUM_WORKSPACE_ID, ATRIUM_TAB_ID — context.
• ATRIUM_HOOK_PORT — TCP port of the hook server. Multi-instance safe: running a release and a dev build side-by-side will use different ports.
• ATRIUM_TASK_ID, ATRIUM_TASK_RUN_ID — set when the pane is bound to a task via task dispatch.
• ATRIUM_EXISTING_PROMPT_COMMAND — the user's original bash PROMPT_COMMAND, preserved so atrium's hooks chain cleanly.
• ATRIUM_REAL_ZDOTDIR, ATRIUM_BOOTSTRAP_ZDOTDIR — internal bootstrap for zsh.

Backup and restore

A full backup is cp -R ~/.atrium ~/atrium-backup. To migrate to a new machine:

1. Copy the directory.
2. On the new machine, install atrium.
3. Before first launch, replace ~/.atrium with the copy. atrium will find all your workspaces, adapters, themes, and tasks.

The CLI binary (bin/atrium) is re-installed on launch, so you don't need to worry about architecture mismatches when moving between Intel and Apple Silicon machines.