Skip to main content
This quickstart walks through installing Gandalf, capturing a content-backed snapshot of your user-global Codex or Claude Code setup, diffing it against your current state, and previewing a restore. No files are changed until you explicitly opt in with --apply --experimental.

​
Prerequisites

  • macOS or Linux (amd64 or arm64).
  • A user-global setup for at least one of Codex (~/.codex/) or Claude Code (~/.claude/).

​
1. Install

See Install for more details.

​
2. Open the terminal workspace

Running gandalf with no arguments opens the Changes-first Home in the Bubble Tea TUI:
The sidebar links Home, Console, Changes, Timeline, and Saves. The Console tabs cover Hooks, Plugins, Marketplace, Skills, and MCP Servers. Every write begins with Review Changes.

​
3. Capture a content-backed baseline

Content-backed snapshots are what make restore safe. They require an explicit --agent and --scope user for a currently supported agent.
Snapshots are written to ~/.gandalf (or $GANDALF_STORE). List and inspect them:

​
4. Diff against your current state

Change something in your agent setup (add a skill, edit a hook), then compare:
The output separates semantic changes (typed entities such as MCP server entries) from raw source changes (file-level additions and removals). Add --json for machine-readable output.

​
5. Preview a restore

Dry-run is the default and never writes:
The plan lists writable changes, unsupported items with reasons, per-item risk, and rollback instructions.

​
6. Apply after review

Applying requires both --apply and --experimental (or GANDALF_EXPERIMENTAL=1). Gandalf creates a pre-apply restore point before writing.
Add --rollback to automatically undo on failure:

​
Next steps

Terminal workspace

Navigate Home, Console, Changes, Timeline, and Saves.

Bundles

Export, verify, and import portable .gandalf archives.

Team manifest

Declare shared MCP servers and skills in gandalf.toml.

Trust contract

Read the safety boundaries Gandalf promises.