Data directory: what atrium writes to ~/.atrium

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

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

The active path is exported as ATRIUM_DATA_DIR in every pane.

An SSH location has its own atrium data directory on that box. Its daemon owns remote project snapshots, tasks, notes, scrollback, and sessions; the Mac does not mirror those trees under its local ~/.atrium/. Use location-aware CLI routing instead of constructing a remote path locally.

Layout

A workspaces/{id}/ directory is a project — the CLI and on-disk layout keep the pre-v0.195.0 vocabulary. See Naming.

~/.atrium/
├── config.json                   ← user configuration
├── state.json                    ← app-level state (open projects, workspaces, window geometry)
├── tasks.db                      ← SQLite: tasks, runs, segments, comments, labels, statuses
├── timeline.db                   ← SQLite: the workspace event feed
├── runtime.pid                   ← the running daemon
│
├── workspaces/
│   └── {workspace-id}/           ← one PROJECT
│       ├── workspace.{ts1}.json  ← project snapshot (rotated)
│       ├── workspace.{ts2}.json
│       └── notes/                ← notepad notes for this project
│
├── agents/
│   └── {slug}/agent.md           ← agent definitions (`++slug` references)
│
├── memory/                       ← durable facts; disk is truth, the index is derived
├── skills/                       ← user-authored skills
├── chat/                         ← agent-chat session state and transcripts
├── snapshots/                    ← content-addressed Vault history
├── captures/                     ← QA Capture bundles (CAP-#)
├── library/                      ← saved rooms and panes
├── wallpapers/                   ← wallpaper sources
├── logs/                         ← on-disk app + daemon logs
├── previous/                     ← the app generation the last update superseded
│
├── 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)
│
└── diagnostics/                  ← optional; only when diagnostics are enabled
    └── trace.{timestamp}.json

Claude account credentials live in claude-accounts-tokens.json with 0600 permissions, written and read only by the Rust side — they never enter the webview or app state. See Accounts & quota.

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_SOCKET — the control socket of the instance that spawned this pane. Together with ATRIUM_DATA_DIR, this is how a pane reaches its own instance. Never infer the data directory from a channel name — a second worktree or dev build resolves differently and you will read the wrong instance's state.
• ATRIUM_PANE_ID — pane UUID.
• ATRIUM_WORKSPACE_ID, ATRIUM_TAB_ID — the project and room. (WORKSPACE means project, TAB means room.)
• 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.

That command backs up the local Mac only. Back up each remote location's data and repositories on that machine using your normal server backup process; unregistering a location does not copy or delete its data.