atrium — Docs
docs/concepts/persistence.md

Persistence: how atrium survives crashes and reboots

What atrium journals to ~/.atrium — layouts, scrollback, sessions, tasks — how atomic writes and Vault history work, and what restores after a crash.

atrium's durability guarantee is simple: if you can quit and reopen the app and see your work unchanged, a crash or a reboot should produce the same result.

Two things carry that guarantee. This page covers the journal — what lands on disk and how it comes back. The daemon covers the other half: agents that never stopped running in the first place.

What gets persisted

Local atrium state lands on disk under ~/.atrium/. A remote project's equivalent state lands in the data directory of its owning location:

  • App-level state (state.json) — which projects are open, which project is focused, window geometry.
  • Per-project state (workspaces/{id}/workspace.json) — project metadata, the list of rooms, each room's mosaic tree, and pane snapshots such as cwd, session references, editor view state, browser URL and history, and notepad viewport state. Terminal scrollback is stored separately.
  • Configuration (config.json) — theme, keybinding overrides, terminal and markdown editor settings, telemetry preferences, LSP overrides, worktree defaults.
  • Tasks and runs (tasks.db) — SQLite database with cards, statuses, labels, comments, runs, segments.
  • Reviews (review.db) — SQLite database with diff-review comment threads, attribution, and state changes.
  • Themes (themes/*-custom.json) — user-created custom themes.
  • Adapters (adapters/<name>/) — installed adapter manifests and scripts.
  • Snapshot history (.git/) — a Git repository in the data directory stores point-in-time state captures. snapshots/ holds exports and snapshot bookkeeping (see Snapshots & Vault below).
See Data directory for the full layout and schemas.

How journaling works

atrium does not wait for you to hit save:

  1. Dirty tracking — every state mutation bumps a dirty flag. A heartbeat writer checks the flag and skips writes when nothing changed.
  2. Atomic writes — state is written to a temporary file and renamed over the canonical file, so a reader does not see half-written JSON.
  3. Snapshot history — periodic and event-triggered Git snapshots preserve earlier versions for recovery through the Vault. Older timestamped project journals remain a read fallback during upgrades; current builds write workspace.json.
On macOS and Linux, state files are written with 0600 permissions and state directories with 0700. Windows uses filesystem ACLs.

Restoring on launch

On launch:

  1. Read state.json to find open projects and the focused one.
  2. Load each project's canonical state from workspaces/{id}/workspace.json.
  3. Rebuild the mosaic tree for each room.
  4. Materialize each pane according to its type.
Pane-specific restore. Terminal panes attach to a surviving daemon PTY or spawn a fresh one, replay scrollback into the xterm grid, and call the adapter's resume path when needed. Editors reopen the file and restore Monaco state. Browser panes navigate to their last URL and replay navigation history. Notepad panes rehydrate the active note and viewport. Git, search, and task panes restore their expanded sections, queries, and filters.

While the app starts, the launching screen shows live restore progress with the project currently being rehydrated and a per-step status. If a step hangs for more than a few seconds the screen surfaces a stuck? reload escape hatch — clicking it triggers a fresh launch instead of leaving you staring at a spinner.

The RestoreChooser is the recovery UI shown when atrium detects that the last exit was unclean. It lists rooms and panes with running-process indicators so you can choose which to restore. A setting (and a toggle on the chooser itself) lets you skip the chooser and auto-relaunch your last session on every launch, if you'd rather always pick up exactly where you left off.

Lazy pane mount

Inside a running project, atrium lazy-mounts panes at two levels:

  • Project level — panes in a project other than the active one aren't mounted at all until you switch to that project. Their snapshots are loaded into atoms, so the layout previews are correct, but their React components don't run.
  • Room level — within the active project, only the panes in the focused room (and a small window of recent rooms) are mounted. Panes that scroll off the focused room remain in the project atoms; their components remount when the room becomes active again.
Pane state lives in app-level atoms rather than component-local React state, so a remount restores the pane to exactly the state it was in. The editor, markdown, git, tasks, review, and search panes all preserve their cursor, selection, scroll, expanded sections, modal state, and in-flight drafts across remount. The browser pane hides its CEF NSView on unmount and restores it on remount instead of tearing down the engine.

Agent session resume

Agent panes go through an extra step:

  1. atrium looks up the pane's stored session ID.
  2. Terminal panes use the adapter's resume command and saved session reference. Chat panes resume over their transport instead of launching a terminal command.
  3. If the saved session cannot be resumed, atrium surfaces the failure instead of silently substituting a fresh conversation.
Sessions the daemon is still running are adopted rather than relaunched: atrium re-subscribes and replays, so a restart never produces two copies of the same agent. A daemon restart marks its sessions interrupted rather than faking liveness.

The same rule applies to remote locations. If a location was unreachable when the desktop app opened, its last-known state remains read-only; when the connection returns, atrium attaches to the remote daemon's existing rooms, sessions, PTYs, and scrollback.

This gives agents the same survivability as plain terminals: your conversation history is preserved, not just the terminal scrollback.

What does not resume

  • Unsaved editor buffers are flushed to disk on close; there is no separate unsaved-buffer journal.
  • In-flight HTTP requests and long-running foreground shell commands (not adapter-managed) do not resume — the command finishes or is killed when the process dies. The pane records the last command so the activity sidebar can offer a Replay action.
  • Browser pane cookies do not carry over across CEF engine upgrades (for example, moving from WKWebView to Chromium). Sign-ins made before the upgrade must be redone once.
  • Never-prompted terminal sessions — a terminal agent started without any user input can be launched fresh on restore, with its saved launch flags. A session with conversation history follows the resume path; an unavailable history is not silently replaced with a blank conversation.

Snapshots and Vault

The data directory is also a Git repository: ~/.atrium/.git/ holds the snapshot history surfaced by the Library as the Vault. Each snapshot captures allowed state files, including project layouts, configuration, notes, and a consistent export of the tasks database. It is not a backup of your repositories, agent credential stores, caches, or terminal scrollback.

A snapshot is committed when any of the following triggers fires:

  • Interval — every 30 minutes by default when state has changed since the last commit. Change it under Settings → General → Backups, from every 5 minutes to every 4 hours, or Off. Turning this off leaves pre-update, pre-restore, and shutdown snapshots enabled.
  • Shutdown — on clean exit, after the final state flush.
  • Pre-update — before tauri-plugin-updater installs a new build.
  • Pre-restore — automatic safety net before the user restores from any earlier snapshot.
  • Manual — when you click Take snapshot now in the Vault.
  • Event — when something destructive happens (project deleted, settings reset, bulk-delete from the Library).
Skippable triggers (Interval, Shutdown, event-driven) no-op when the canonical state hash matches the previous snapshot. User-initiated and safety-net triggers always commit. A retention engine prunes old snapshots according to a tiered policy (more recent commits kept densely, older commits sparsely).

Restoring from a snapshot opens a restore dialog that semantically diffs the snapshot against current state — file by file for project JSON, row by row for tasks.db — so you can preview exactly what will change before confirming. A pre-restore snapshot is committed first, so the restore is itself reversible. A shutdown gate prevents the app from exiting mid-snapshot.

Each snapshot is a Git commit. The tasks exporter writes a consistent SQLite copy using VACUUM INTO, plus JSON sidecars for readable diffs. Unchanged files reuse existing Git objects.

Manually clearing state

  • Remove a specific project: delete its directory under ~/.atrium/workspaces/{id}/.
  • Reset all app state but keep configuration: rm -rf ~/.atrium/workspaces ~/.atrium/state.json.
  • Full reset: rm -rf ~/.atrium. This deletes configuration, snapshots, the Vault history, custom themes, installed adapters, and task data.
Those commands affect the local machine only. Remove remote data on the owning box; unregistering a location leaves its files and repositories untouched.