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).
How journaling works
atrium does not wait for you to hit save:
- Dirty tracking — every state mutation bumps a dirty flag. A heartbeat writer checks the flag and skips writes when nothing changed.
- Atomic writes — state is written to a temporary file and renamed over the canonical file, so a reader does not see half-written JSON.
- 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.
0600 permissions and state directories with 0700. Windows uses filesystem ACLs.
Restoring on launch
On launch:
- Read
state.jsonto find open projects and the focused one. - Load each project's canonical state from
workspaces/{id}/workspace.json. - Rebuild the mosaic tree for each room.
- Materialize each pane according to its type.
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.
Agent session resume
Agent panes go through an extra step:
- atrium looks up the pane's stored session ID.
- Terminal panes use the adapter's resume command and saved session reference. Chat panes resume over their transport instead of launching a terminal command.
- If the saved session cannot be resumed, atrium surfaces the failure instead of silently substituting a fresh conversation.
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-updaterinstalls 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).
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.