Skip to main content
Gandalf is a local, TUI-first control console for user-global AI agent setup across Codex and Claude Code. It inspects installed skills, hooks, MCP servers, and plugins, browses agent-native marketplace and source entries, and applies only reviewed, provider-backed changes with content-backed snapshots for safe rollback.

Quickstart

Install Gandalf, capture your first baseline, and preview a restore.

Install

Homebrew, install script, and Go source builds.

Concepts

Snapshots, Review Changes, providers, and marketplace sources.

CLI Reference

Every gandalf subcommand with flags and examples.

​
What Gandalf does

  • Inspects local setup. Read-only scan of user-global Codex (~/.codex/) and Claude Code (~/.claude/) skills, hooks, MCP servers, and plugins.
  • Captures snapshots. Content-backed or metadata-only saves of your current agent state.
  • Diffs setup. Semantic and raw-source changes between any two snapshots (or a snapshot and current).
  • Reviews changes. Every mutating action shows a preview first; apply requires explicit flags.
  • Rolls back. Restore from a snapshot with dry-run and rollback safety nets.
  • Bundles state. Exports portable .gandalf archives you can verify, inspect, and import on another machine.
  • Team manifest. Declare a shared agent environment in gandalf.toml and sync it across your team.

​
What Gandalf is not

  • Not a sync tool between Codex and Claude Code.
  • Not a marketplace: it browses agent-native sources but does not certify them.
  • Not a multi-tool skill fan-out: every mutation is scoped, reviewed, and provider-backed.

​
Current support

Gandalf’s active scope is user-global setup for Codex and Claude Code. Project-local files (.mcp.json, project AGENTS.md, .env) are out of scope. See the support matrix for details.

​
Trust contract

Gandalf reads local agent config only, does not execute MCP commands or hooks, does not use the network unless GANDALF_UPDATE_CHECK=1 is set, and requires explicit apply flags before mutating writes. Full contract on Trust contract.