atrium — Docs
docs/reference/data-directory.md

Data directory: what atrium writes to ~/.atrium

The full ~/.atrium layout — config.json, state.json, tasks.db, workspace snapshots, agents, themes, adapters, the env vars atrium sets, and backups.

atrium stores its instance data under your home directory. The usual locations are:

  • Public Beta and Stable — ~/.atrium/
  • Beta — ~/.atrium-beta/
  • Primary dev build — ~/.atrium-dev/
  • Dev worktrees — ~/.atrium-dev-<instance>/, one directory per worktree
On Windows, ~ normally means %USERPROFILE%. The active path is exported as ATRIUM_DATA_DIR in every pane. Use that path instead of deriving one from the channel name: two dev instances can use different directories.

ATRIUM_DATA_DIR is something atrium sets, not a setting it reads. The CLI and agents use it to find their instance. Setting it before you launch the app does not move the app's data, and the installed app always uses the directory for its channel. ATRIUM_INSTANCE names a separate instance (~/.atrium-dev-<instance>/) only in dev builds; release builds ignore it. To try a clean state with an installed build, follow Backup and restore: stop atrium and its background daemon, move the data directory aside, then move it back when you are done.

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
├── telemetry_queue.db            ← queued app telemetry
├── device-id                     ← anonymous installation identifier
├── runtime.pid                   ← the running daemon
├── ipc/                          ← daemon lock records and Unix sockets
├── runtime/                      ← paired-device records and daemon support state
├── .git/                         ← app-state snapshot history used by the Vault
│
├── workspaces/
│   └── {workspace-id}/           ← one PROJECT
│       ├── workspace.json        ← current project record
│       └── 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/                    ← snapshot bookkeeping
├── 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/                  ← recorder traces, profiles, and manual bundles
    └── perf-<timestamp>.ndjson

Claude account credentials can live in claude-accounts-tokens.json and claude-accounts-oauth.json, with owner-only file permissions (0600 on Unix, an owner-only ACL on Windows). These files are separate from public account metadata. See Accounts & quota.

Custom provider definitions are part of app state. Their API keys are stored separately in the operating system's credential store, scoped to the atrium instance: Keychain on macOS, Credential Manager on Windows, and the login keyring on Linux. Copying the data directory does not copy those keys; enter them again on the destination machine.

config.json

User configuration. See Configuration for the schema.

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

state.json

App-level state. Not for hand-editing.

{
  "openWorkspaces": ["<workspace-id>"],
  "focusedWorkspace": "<workspace-id>",
  "windowGeometry": { "x": 100, "y": 100, "width": 1600, "height": 1000 }
}

The file also carries namespaced settings such as launch profiles and each client's view of shared rooms. Saves are atomic and unchanged content is skipped. Shared room membership and a client's active room or mosaic layout have separate owners, so one connected computer's focus need not move another's.

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.json

The current project record, including rooms, panes, session references, and project settings. Fields use camelCase. A small illustrative subset is:

{
  "id": "<uuid>",
  "name": "atrium",
  "projectDir": "/path/to/project",
  "isWorktree": false,
  "parentWorkspaceId": null,
  "worktreeBranch": null,
  "worktreeBaseRef": null,
  "tabs": [],
  "panes": {},
  "focusedPaneId": null
}

atrium writes workspace.json atomically. The Vault's snapshots provide history and recovery. Timestamped workspace.<timestamp>.json files belong to older versions; the reader can use them during migration, and successful canonical writes clean up legacy files.

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.

Snapshot history and legacy journals

Current app-state history lives in the data directory's .git/ repository and is exposed through the Vault. The old journal/ state-save mechanism is no longer written; existing journal directories are preserved as journal.legacy.<timestamp>/ during migration.

logs/ and diagnostics/

logs/ contains desktop, daemon, chat-runtime, browser, and frontend error records. These are separate from optional performance recording. The diagnostics/ directory contains perf-*.ndjson traces and manually requested profiles or ZIP bundles. See Diagnostics for filenames, retention, and inspection guidance.

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 endpoint of the instance that spawned this pane: a Unix socket or Windows named pipe. 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 local backup includes the whole active data directory, including hidden files. Stop the instance, including its background daemon, before copying so its databases are no longer being written. On macOS or Linux, cp -R ~/.atrium ~/atrium-backup copies the standard instance; use the actual instance path when different. To migrate to a new machine:

  1. Copy the directory.
  2. On the new machine, install atrium.
  3. Before first launch, place the copy at the destination instance's data path. Saved projects, themes, tasks, and layouts travel with it, but project directories must exist at usable paths and account credentials may need to be entered again.
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 atrium's local data only, not the repositories it references or credentials in the operating system's credential store. 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.