Description

01-snapshot-home-directory-hang.md

Issue: Snapshot on home directory hangs opencode indefinitely

Summary

Running opencode from the home directory (~) causes the program to freeze completely because it tries to create a git-based snapshot of the entire home folder — which can be hundreds of gigabytes with tens of thousands of files.

The Problem (non-technical)

Imagine you sit down at your computer, open a terminal, type opencode, and the program starts... but then nothing responds. You cannot type, you cannot click, you cannot even close it cleanly. You have to open another terminal and force-kill it.

This happens because opencode, when it starts, tries to take a "snapshot" of every file in the current directory so it can track changes later. If you are in your home folder — which might have your Desktop, Documents, Downloads, and years of accumulated files — that snapshot can take many minutes or even hours. During that time, the program is completely frozen.

Technical Explanation

opencode's architecture uses an internal git worktree for its snapshot system (implemented in opencode/src/backend/snapshot.ts). When a session starts, it:

1. Initializes a bare git repository under ~/.local/share/opencode/snapshot/<hash>/
2. Runs git add --all --sparse against the workspace root directory
3. Blocks the TUI event loop until this git operation completes

When the workspace root is the home directory (~):

• Size: The home directory in our case is 223 GB with ~20,000 modified files
• Git overhead: The home directory itself is already a git repository (with no .gitignore), so git scans all tracked files
• No progress indicator: The TUI shows no spinner, no progress bar, no timeout
• No cancellation: There is no way to cancel or interrupt the snapshot; Ctrl+C is not captured

The log shows evidence of this:

message=tracking hash=<sha1> cwd=/home/user git=/home/user/.local/share/opencode/snapshot/<hash>/<bare>

But during the actual snapshot operation, even logging pauses because git add is blocking the event loop.

Steps to Reproduce

# Prerequisite: your home directory should be a git repo
# or contain many files (common for any long-term user)
cd ~

# Run opencode
opencode

# Result:
# - TUI appears for ~1 second
# - Then the interface freezes
# - CPU goes to 100% (git process)
# - No keyboard input works
# - Must kill with: kill -9 $(pgrep opencode)

Current Workaround

Set "snapshot": false in ~/.config/opencode/opencode.json:

{
  "snapshot": false
}

This disables all snapshot functionality, which means the undo/revert feature no longer works.

Suggested Fixes (any one would help)

1. Auto-detect workspace scope: If the workspace is the home directory (or any directory that is unusually large), either disable snapshots automatically or warn the user.

2. Timeout mechanism: Set a 30-second timeout on snapshot initialization. If git add does not complete within that time, disable snapshots for the session and continue.

3. Progress indicator: Show a spinner or progress bar during snapshot init so the user knows what is happening instead of seeing a frozen screen.

4. Async snapshot: Run the snapshot in a background thread/coroutine and allow the TUI to become interactive immediately. The snapshot completes whenever it completes.

5. Respect .gitignore: If the workspace root already has a .gitignore, use it to exclude common large directories (node_modules, .cache, .local, etc.) from the snapshot.

Plugins

No response

OpenCode version

No response

Steps to reproduce

No response

Screenshot and/or share link

No response

Operating System

No response

Terminal

No response