Understanding the Disposable Worktree in no-mistakes: Architecture and Safety

The disposable worktree in no-mistakes is a detached Git worktree created under ~/.no-mistakes/worktrees/<repo-id>/<run-id>/ that isolates every pipeline execution from your local repository, ensuring that destructive operations like rebasing, force-pushing, and auto-fixing never corrupt your working copy.

The no-mistakes repository implements a strict isolation boundary by running all pipeline steps inside a temporary Git worktree. This design lives at the core of the tool’s architecture, allowing daemon-managed agents to freely modify, test, and commit code while keeping the developer’s original checkout completely untouched. According to the project documentation in docs/src/content/docs/start-here/introduction.md, the system “spins up a disposable worktree” for every run, establishing a sandbox where automated refactoring and CI steps can operate safely.

Core Purpose of the Disposable Worktree

At its heart, the disposable worktree serves as a protective boundary between the developer’s workspace and the daemon’s execution environment. Located at ~/.no-mistakes/worktrees/<repo-id>/<run-id>/, each worktree is a true Git worktree (implemented as a pointer file in .git referencing a bare repository) that provides standard Git semantics without special handling.

As illustrated in the gate-model diagram at docs/src/content/docs/concepts/gate-model.md, the daemon flows execution through the disposable worktree before reaching pipeline steps. This ensures that any side effects—whether from misbehaving tools, aggressive linters, or history rewrites—remain confined to a directory that can be safely discarded.

Architectural Benefits of the Disposable Worktree

Isolation from the Developer’s Working Copy

The primary goal is absolute isolation. By executing all steps in a separate directory, no-mistakes guarantees that the original checkout remains pristine. The daemon can perform complex file system operations without risking accidental modification of uncommitted changes or untracked files in the developer’s main clone.

Safety for Destructive Operations

Many automation steps require rewriting history. The disposable worktree provides a safe zone where rebase, force-push, and CI auto-fix operations can execute freely. Since the worktree is designed to be temporary, history rewrites happen in an expendable environment that prevents accidental loss of unpushed commits in the user’s primary repository.

Deterministic Environment for Agents

Agents such as Claude, Codex, or Copilot are explicitly steered to keep all intentional writes inside the worktree. This confinement creates a deterministic sandbox that simplifies cleanup, prevents state leakage between runs, and provides a reliable filesystem context for AI agents to operate on without accessing sensitive areas of the host system.

Automatic Cleanup and Crash Recovery

The daemon manages the worktree lifecycle from creation to deletion. As documented in docs/src/content/docs/concepts/daemon.md, the system creates the worktree at the start of a run, executes the pipeline, and removes the directory upon completion or daemon restart. Orphaned worktrees are automatically reaped, ensuring stale state never accumulates on disk.

Consistent Git Semantics

Because the worktree is a genuine Git construct, all standard Git commands function normally. Tools can rely on git rev-parse --git-path working correctly, and the pipeline can reuse existing Git tooling without special-case handling for temporary directories.

Implementation Details

The implementation spans several key components that coordinate to create and manage these isolated environments.

Worktree Path Resolution

The internal/paths/paths.go file defines the location logic for all disposable worktrees:

func (p *Paths) WorktreeDir(repoID, runID string) string {
    return filepath.Join(p.root, "worktrees", repoID, runID)
}

This helper constructs the path ~/.no-mistakes/worktrees/<repo-id>/<run-id>/, ensuring consistent directory organization across the system.

Executor Integration

Inside internal/pipeline/executor.go, the executor receives the worktree path as the execution directory for all pipeline steps:

func (e *Executor) Run(ctx context.Context, run *db.Run) error {
    // workDir is the disposable worktree for this run
    workDir := run.WorkDir
    // All steps (rebase, test, lint, etc.) operate under workDir
    ...
}

Every step defined in internal/pipeline/steps/*.go operates within this workDir, guaranteeing that file system modifications remain isolated.

Daemon Orchestration

The internal/daemon/manager.go orchestrates the lifecycle, invoking the worktree creation logic before pipeline execution and triggering cleanup routines afterward. This ensures that even if a run crashes or the daemon restarts, no permanent worktree directories persist indefinitely.

Inspecting Your Disposable Worktree

You can locate and verify the worktree for any specific run using the CLI:

# Show the worktree created for the current run (run ID is printed in `axi run`)

worktree=$(nm paths worktree-dir <repo-id> <run-id>)
echo "Worktree path: $worktree"

# Verify it is a detached worktree

git -C "$worktree" rev-parse --verify HEAD   # shows the detached HEAD SHA

This confirms that the pipeline is operating on a detached HEAD in an isolated directory, completely separate from your working repository.

Summary

• The disposable worktree is a detached Git worktree created under ~/.no-mistakes/worktrees/<repo-id>/<run-id>/ for every pipeline execution.
• It provides complete isolation from the developer’s working copy, preventing accidental corruption of local changes.
• Destructive operations like rebasing and force-pushing occur safely within the worktree, protecting the main repository’s history.
• The daemon manages automatic lifecycle handling, creating the worktree at startup and cleaning it up after completion or crashes.
• Implementation resides in internal/paths/paths.go, internal/pipeline/executor.go, and internal/daemon/manager.go, with documentation in docs/src/content/docs/concepts/daemon.md.

Frequently Asked Questions

Where are disposable worktrees stored in no-mistakes?

Disposable worktrees are stored under ~/.no-mistakes/worktrees/<repo-id>/<run-id>/. The internal/paths/paths.go file defines the WorktreeDir function that constructs this path, ensuring each run receives its own isolated directory based on the repository ID and run ID.

How does the disposable worktree prevent corruption of my local changes?

The worktree acts as a physical isolation boundary. Because the daemon operates exclusively within the disposable directory (configured as workDir in internal/pipeline/executor.go), it never touches files in your original Git clone. Even if an agent malfunctions and writes garbage to the filesystem, those changes occur only in the temporary worktree that gets deleted after the run.

What happens to the worktree after a pipeline run completes?

The daemon automatically removes the worktree directory upon run completion, success or failure. According to the architecture described in docs/src/content/docs/concepts/daemon.md, the system also reaps orphaned worktrees on daemon restart, ensuring that crashed runs or interrupted processes do not leave stale directories consuming disk space.

Why does no-mistakes use Git worktrees instead of simple temp directories?

Git worktrees provide consistent Git semantics that temporary directories cannot match. As a true Git worktree (referencing the bare repository via a pointer file), commands like git rev-parse --git-path work identically to regular repositories. This allows the pipeline to reuse existing Git tooling without special handling, while still maintaining the ability to perform destructive operations safely in an isolated context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}