Snapshots

tip

Snapshots give you a safety net — you can undo any agent change made during the session.

How Snapshots Work

Under the hood, opencode maintains an internal git repository separate from your project's version control. Every agent operation that modifies files creates a commit in this internal repository. The snapshot system is:

Internal Storage

The snapshot repository is stored in the opencode data directory. The exact location depends on your operating system:

Platform	Default Snapshot Location
Linux	~/.local/share/opencode/snapshots/
macOS	~/Library/Application Support/opencode/snapshots/
Windows	%APPDATA%/opencode/snapshots/

Each session gets a unique subdirectory. The internal repository uses the same object model as git but operates in isolation from any git repository in your project directory.

What Gets Snapshotted

Every file system mutation by an agent is recorded:

• File creation – The full new file content is stored.
• File modification – A diff between the previous and new content is stored. For files over 10 MB, the entire new content is stored rather than a diff.
• File deletion – The original file content is preserved so the deletion can be undone.
• Directory creation – The directory path and creation time are recorded.
• File rename or move – Both the old and new paths are tracked.

Undo and Redo

Snapshots power the /undo and /redo commands for in-session recovery.

Undo

/undo

Reverts the most recent agent file operation. Each invocation steps back one change. You can undo multiple times to walk back through the entire session's change history.

What happens during an undo:

1. opencode reads the snapshot for the most recent file change.
2. If the change was a file edit, the original content is restored.
3. If the change was a file creation, the file is deleted.
4. If the change was a file deletion, the file is recreated with its original content.
5. The undo is recorded in the redo stack.

Redo

/redo

Reapplies a change that was previously undone. Redo is available only for changes that were undone in the current session. Once a new change is made (a new edit, create, or delete), the redo stack is cleared.

Limitations

note

The undo stack is per-session and is cleared when the session ends.

Configuration

Snapshots are enabled by default. To disable them:

{
  "snapshot": false
}

When to Disable Snapshots

Disabling snapshots can be beneficial in specific scenarios:

• Very large repositories – The internal git operations add overhead on every file write. In monorepos with hundreds of thousands of files, disabling snapshots improves performance.
• Disk-constrained environments – The internal git repository consumes additional disk space proportional to the number of changes made during a session. In long sessions with heavy modification, this can reach hundreds of megabytes.
• Ephemeral sessions – If you never use undo or redo and do not need the safety net, disabling snapshots avoids unnecessary I/O.
• CI/CD environments – Automated pipelines that run opencode do not benefit from undo/redo. Disabling snapshots reduces disk writes and improves throughput.
• Read-only workflows – If you are using opencode for exploration and analysis without writing changes, snapshots are unnecessary overhead.

Tradeoffs

Snapshot Lifecycle

Session Start

When a session begins, opencode creates a new snapshot directory and initializes an empty internal git repository. No snapshots exist yet.

During the Session

Each file mutation triggers the snapshot pipeline:

1. Pre-mutation – If the file exists, its current content is read and stored as the "before" state. The file's path, size, and modification timestamp are recorded.
2. Mutation – The agent's tool call executes (edit, write, delete, etc.).
3. Post-mutation – The new file content is read and stored as the "after" state. A diff is computed between before and after.
4. Commit – The snapshot is committed to the internal repository with metadata: tool name, timestamp, agent name, and a description of the change.

The entire pipeline runs synchronously. The agent does not proceed to the next step until the snapshot is committed. This guarantees that every change is tracked before any dependent operation begins.

Session End

When the session ends:

1. The snapshot directory is marked for cleanup.
2. Old snapshots are garbage collected. The retention policy is configurable but defaults to immediate cleanup on session close.
3. Any pending undo/redo history is discarded.

Snapshot Cleanup

Technical Details

Diff Algorithm

For text files, opencode uses a line-oriented diff algorithm similar to git's default. The diff is stored as a unified diff format, which is compact and fast to compute. For files under 1 MB, diff computation takes under 5 milliseconds.

For binary files and files over 10 MB, no diff is computed. The complete file content is stored in both the before and after snapshots. This trades storage efficiency for reliability: binary diffs are often larger than the files themselves.

Performance Characteristics

File Size	Snapshot Time (average)	Storage per Change
< 10 KB	1-2 ms	~1 KB (diff)
10 KB - 1 MB	2-10 ms	~5 KB (diff)
1 MB - 10 MB	10-50 ms	~50 KB (diff)
> 10 MB	50-200 ms	Full file size

These measurements assume an SSD. HDD performance will be approximately 2-3x slower.

Concurrency

Snapshots are atomic within a single tool invocation. If an agent calls edit on three files in one step, each file is snapshotted independently and sequentially. There is no risk of partial snapshots: either all three files are snapshotted, or none are (if the operation fails before any snapshot completes).

Best Practices

Keep Snapshots Enabled

Disable for CI or Batch Operations

If you run opencode in automated environments, disable snapshots to reduce I/O and disk usage:

{
  "snapshot": false
}

Use With Git

Monitor Disk Usage

In long-running sessions with heavy file modification, the internal snapshot store can grow. If disk space is a concern:

• Restart sessions periodically to clear the snapshot history.
• Disable snapshots for projects where you rarely need undo.
• Monitor ~/.local/share/opencode/snapshots/ (or the OS-specific equivalent) for unexpected growth.

Recovery Without Snapshots

If snapshots are disabled and you need to recover from an unintended change:

1. If the project uses git, check git reflog for recent commits.
2. If the editor has local history features, check those.
3. If the file is tracked by the operating system's versioning (macOS Time Machine, Windows File History, Linux LVM snapshots), restore from there.

Related Commands

Command	Description
/undo	Revert the most recent file change
/redo	Reapply a reverted file change
/init	Reset session state (clears snapshot history)
Snapshot status indicator	Shows icon in the interface when snapshots are active