Skip to main content
Gandalf’s model is built on a small set of primitives. Understanding these concepts makes the CLI and TUI predictable: what gets scanned, what can be mutated, what has to be previewed first, and what safety net protects you when something goes wrong.

Snapshots

Content-backed vs metadata-only captures of your agent state.

Review Changes

The mandatory preview before any mutation.

Providers

Only provider-backed rows are actually executable.

Marketplace

Agent-native source browsing and its limits.

Trust Contract

The runtime safety boundaries Gandalf enforces.

Support Matrix

Exactly what is supported per agent today.

​
Supporting vocabulary

  • Evidence is a typed record of a discovered configuration artifact: a config file, an MCP server entry, a permission rule, an env key. Each has a kind, source path, and optional structured value. Scans, snapshots, diffs, and restore plans all speak in evidence.
  • Setup Console is Gandalf’s default TUI screen: a sidebar with Home, Console, Changes, Timeline, and Saves, and Console tabs for Hooks, Plugins, Marketplace, Skills, and MCP Servers.
  • Unified Inventory is the normalized, cross-agent list of setup rows that the Console renders. It groups skills, hooks, MCP servers, and plugins as global/user rows with compact agent identity, so you never pick an agent picker before you see your setup.
  • Changes-First Home summarizes drift from the latest supported baselines before you enter inventory browsing or recovery flows. It is read-only: Review opens the detailed environment diff, and rollback still goes through Review Changes before Apply.

​
How they fit together

  1. gandalf scan discovers evidence read-only.
  2. gandalf snapshot create persists evidence (metadata or content-backed) to the store.
  3. gandalf diff compares two snapshots (or a snapshot and current) as semantic changes plus raw source changes.
  4. The TUI and CLI expose actions only when a provider can preview and execute them.
  5. Every mutation surfaces a Review Changes preview first.
  6. gandalf restore uses a content-backed snapshot as the safety net for rollback.