Snapshots

The snapshot system tracks every file change made by agents during a session, enabling reliable undo and redo operations. When an agent edits, creates, or deletes files, opencode records a snapshot of the change so you can revert or reapply it at any time.

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:

• Per-session – Snapshots are scoped to the current session. They are discarded when the session ends.
• Automatic – No manual setup is required. Snapshots are enabled by default.
• Transparent – The internal git operations do not interfere with your project's own git history, staging area, or working tree.

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.

Binary files, regardless of size, are stored as complete copies rather than diffs. This ensures that undo/redo operations on binary assets (images, compiled binaries, archives) are lossless.

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

• The undo/redo stack is linear. You cannot undo a specific change in the middle of the history; you must undo sequentially from the most recent change.
• Undo/redo is per-session. Closing the session or starting a new one clears the history.
• Undo/redo does not affect your project's own git history. If you committed a change to the project's git repository, undoing in opencode will not create a revert commit in your project's git.

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

Without snapshots, the following capabilities are lost:

• /undo and /redo commands produce a warning message: "Snapshots are disabled. Changes cannot be rolled back through the CLI or UI."
• There is no way to recover from an unintended agent modification except through your project's own version control (git reflog, manual reverts).
• The session history panel in the interface shows no file change entries.
• Agent audit trails for file modifications are unavailable.

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

Snapshot cleanup happens automatically. You do not need to manage snapshot storage manually. If a session crashes unexpectedly, orphaned snapshot directories are cleaned up on the next opencode startup.

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

For everyday development, leave snapshots enabled. The ability to undo unintended changes far outweighs the minimal performance and storage costs. The overhead is negligible for the vast majority of projects.

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

Snapshots complement your project's git workflow. They do not replace it. Continue committing important changes to your project's version control. Snapshots are a convenience layer for in-session recovery, not a replacement for proper source control.

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