> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegandalf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshot and restore Codex or Claude Code setup

> Capture a content-backed baseline of your Codex or Claude Code user-global setup, diff it, and safely restore with dry-run, apply, and rollback flags.

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

<Steps>
  <Step title="Create a content-backed baseline">
    Content-backed snapshots require an explicit `--agent` and `--scope user` for a supported agent.

    <CodeGroup>
      ```bash Codex theme={null}
      gandalf snapshot create --name baseline --agent codex --scope user --project .
      ```

      ```bash Claude Code theme={null}
      gandalf snapshot create --name baseline-claude --agent claude-code --scope user --project .
      ```
    </CodeGroup>
  </Step>

  <Step title="List and inspect saved snapshots">
    ```bash theme={null}
    gandalf snapshot list
    gandalf snapshot show baseline --json
    ```
  </Step>

  <Step title="Diff against current state">
    Compare the saved baseline with live state. The `current` reference captures live evidence without persisting it.

    ```bash theme={null}
    gandalf diff baseline current --agent codex --scope user --project .
    ```

    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.
  </Step>

  <Step title="Preview a restore">
    Dry-run is the default. It never writes.

    ```bash theme={null}
    gandalf restore --snapshot baseline --dry-run --agent codex --scope user --project .
    ```

    The plan lists snapshot, target project, target home, writable change count, unsupported items with reasons, per-item risk, and rollback instructions.
  </Step>

  <Step title="Apply after review">
    Applying requires both `--apply` and `--experimental` (or `GANDALF_EXPERIMENTAL=1`). Gandalf creates a pre-apply restore point automatically.

    ```bash theme={null}
    gandalf restore --snapshot baseline --apply --experimental --agent codex --scope user --project .
    ```

    Add `--rollback` to automatically undo on failure, and `--fail-fast` to stop on first error:

    ```bash theme={null}
    gandalf restore --snapshot baseline --apply --experimental --rollback --fail-fast --agent codex --scope user --project .
    ```
  </Step>
</Steps>

<Warning>
  `restore --apply` mutates local user-global agent config. It requires `--experimental` or `GANDALF_EXPERIMENTAL=1`. Always run `--dry-run` first and review the plan.
</Warning>

## Related

* [Snapshots concept](/concepts/snapshots)
* [Review Changes](/concepts/review-changes)
* [`gandalf restore` reference](/cli/restore)
* [Trust contract](/trust-contract)