Snapshots

Shadow-git snapshots capture your workspace at turn boundaries so you can review what an agent changed and undo it without touching your real git history.

Overview

When snapshots are enabled, docker-agent records the state of your working directory as the agent runs. Each checkpoint is stored in a shadow git repository kept under the docker-agent data directory — completely separate from your project’s own .git. This lets you:

• Review exactly which files an agent touched on a given turn.
• Undo the most recent change with /undo.
• Reset the workspace back to any earlier checkpoint — or all the way to its pre-agent state.

Snapshots only ever touch files on disk. They never write commits to your repository, never move your HEAD, and never appear in git log or git status.

Enabling Snapshots

The simplest way is to enable snapshots globally for every agent in your user config:

# ~/.config/cagent/config.yaml
settings:
  snapshot: true

Omit snapshot or set it to false to leave automatic snapshots off.

You can also wire the snapshot built-in hook into a single agent instead of enabling it globally:

hooks:
  turn_start:
    - type: builtin
      command: snapshot
  turn_end:
    - type: builtin
      command: snapshot
  session_end:
    - type: builtin
      command: snapshot

Manually configured snapshot hooks always run, even when settings.snapshot is unset. See examples/snapshot_hooks.yaml for a complete configuration.

Using Snapshots in the TUI

When snapshots are enabled, the TUI exposes two slash commands:

• /undo restores files from the most recent snapshot (one step back).
• /snapshots opens a dialog listing every captured snapshot and the number of files in each. Use ↑/↓ (or j/k) to highlight an entry, then press r to reset the workspace to that point. Pick <original> to revert every snapshot and bring the workspace back to its pre-agent state. Esc closes the dialog without changing anything.

Neither command removes messages from the session transcript — they only touch files on disk. Both commands (and their command-palette entries) are hidden when snapshots are turned off.

How It Works

• Shadow repository. The first time a snapshot is taken for a worktree, docker-agent initializes a separate shadow git directory under the data directory (~/.cagent/snapshot/... by default), keyed by a hash of the worktree path. The shadow repo stores tree objects only — it never writes commits and never touches your source repository’s .git.
• Ignore rules are mirrored. Before each capture, the source repository’s .gitignore and info/exclude rules are mirrored into the shadow repo so ignored files never appear in snapshots.
• Large files are skipped. Newly-added files larger than 2 MiB are excluded from snapshots to keep the shadow repo small.
• Checkpoints only on change. A checkpoint is recorded only when files actually changed, so a final no-op model response does not hide the last meaningful snapshot.
• Scoped to the working directory. Snapshot operations are scoped to the agent’s working directory within the worktree, so a sub-directory agent only captures and restores files under that directory.
• Garbage collection. Wiring snapshot into session_end (or enabling it globally) runs git gc against the shadow repo so old, unreferenced objects are pruned over time.

See Also

• Hooks — the snapshot built-in and the events it can run on.
• Terminal UI — the /undo and /snapshots commands.
• examples/snapshot_hooks.yaml — a complete snapshot hook configuration.