Skip to main content
This guide walks through capturing a safety baseline for your Codex or Claude Code user-global setup, comparing it to your current state, and restoring it if something goes wrong. Restore never writes until you explicitly opt in with --apply --experimental.
1

Create a content-backed baseline

Content-backed snapshots require an explicit --agent and --scope user for a supported agent.
2

List and inspect saved snapshots

3

Diff against current state

Compare the saved baseline with live state. The current reference captures live evidence without persisting it.
Output separates semantic changes (typed entities such as MCP server entries) from raw source changes (file-level additions and removals). Add --json for structured output.
4

Preview a restore

Dry-run is the default. It never writes.
The plan lists snapshot, target project, target home, writable change count, unsupported items with reasons, per-item risk, and rollback instructions.
5

Apply after review

Applying requires both --apply and --experimental (or GANDALF_EXPERIMENTAL=1). Gandalf creates a pre-apply restore point automatically.
Add --rollback to automatically undo on failure, and --fail-fast to stop on first error:
restore --apply mutates local user-global agent config. It requires --experimental or GANDALF_EXPERIMENTAL=1. Always run --dry-run first and review the plan.