How the no-mistakes Git Proxy Gate Model Functions: A Technical Deep Dive

The no-mistakes git proxy gate model functions by installing a local Git proxy remote that intercepts pushes, validates them through an AI-driven pipeline inside isolated disposable worktrees, and only forwards the branch to the upstream repository after every gate passes.

The kunchenguid/no-mistakes repository implements a "gate-before-push" workflow that prevents unvalidated code from ever reaching your upstream remote. Instead of pushing directly to origin, developers push to a local proxy remote called no-mistakes, which triggers a background daemon to execute a deterministic validation pipeline before forwarding the commit.

The Git Proxy Remote Architecture

The git proxy remote serves as the controlled entry point to the gate model. When you run no-mistakes init or the setup wizard, the tool adds a special remote named no-mistakes to your repository configuration.

Setting Up the Proxy Remote

The remote points to a locally running daemon rather than a network URL. In your .git/config, you will see an entry like:

[remote "no-mistakes"]
    url = no-mistakes://localhost:12345
    fetch = +refs/heads/*:refs/remotes/no-mistakes/*

This URL scheme routes Git traffic to the local daemon. As documented in docs/src/content/docs/start-here/introduction.md, developers initiate the gated workflow using git push no-mistakes <branch> instead of git push origin <branch>.

Post-Receive Hook Validation

When the daemon receives the push, a post-receive hook triggers inside internal/wizard/wizard.go. This hook validates that the push originated from the no-mistakes proxy and hands control to the daemon process. The hook ensures that only traffic passing through the proxy enters the pipeline, rejecting direct pushes that attempt to bypass the gate model.

The Daemon and Isolated Worktrees

The daemon (implemented in internal/daemon/lock.go) orchestrates the entire validation process. It guarantees that only one daemon instance operates on a given NM_HOME directory at a time, preventing race conditions through an exclusive OS-level lock.

Exclusive Locking Mechanism

According to internal/daemon/lock.go, the daemon acquires an exclusive lock on startup. This singleton pattern ensures that concurrent pushes to the same workspace are serialized and processed safely, avoiding conflicts in the shared worktree cache.

Creating Disposable Worktrees

The daemon creates a disposable worktree inside <NM_HOME>/worktrees for each push. As implemented in internal/git/git.go, this worktree mirrors the pushed branch but remains completely isolated from the developer’s working directory. All pipeline steps execute inside this sandbox, leaving the developer’s workspace untouched regardless of test failures or linting errors.

The simplified flow in the daemon looks like this:

func (d *Daemon) handlePush(ctx context.Context, ref string) error {
    wt, err := d.paths.NewWorktree(ctx, ref) // creates isolated worktree
    if err != nil { return err }
    return pipeline.Run(ctx, wt) // runs the ordered gates
}

The Validation Pipeline

The pipeline is a fixed ordered chain of gates defined in internal/pipeline/pipeline.go. Each gate must pass before the next begins, creating a deterministic validation sequence.

The Eight-Stage Gate Chain

The pipeline executes the following gates in strict order:

intent → rebase → review → test → document → lint → push → PR → CI

Each gate represents a validation checkpoint. The intent gate captures the developer’s purpose, rebase ensures clean history, review runs AI-driven code analysis, test executes the test suite, document checks documentation coverage, lint enforces style rules, push forwards to the real remote, PR opens the pull request, and CI monitors continuous integration.

Handling Gate Findings and Parking

When a gate discovers issues requiring human intervention, the pipeline enters a parked state. According to internal/pipeline/findings.go, the daemon pauses execution and presents findings through the CLI (no-mistakes axi …) or TUI.

The developer can respond, skip, fix, or abort the gate. For example, the review gate logic works like this:

func (g *ReviewGate) Run(ctx context.Context, wt *Worktree) (Outcome, error) {
    findings := g.runAIReview(wt)
    if len(findings) > 0 {
        return ParkedAtGate(g.Name, findings), nil // runner pauses here
    }
    return Passed, nil
}

Only after the user resolves the findings does the daemon continue to the next gate.

Forwarding to the Upstream Repository

Once all gates pass, the daemon pushes the finalized branch to the configured push target (normally the upstream origin) and creates a clean pull request. As documented in docs/src/content/docs/start-here/introduction.md, this forwarding happens only after validation completes, ensuring the upstream repository never receives a failing or unreviewed commit.

Proxy Environment Configuration

When running as a system service, the daemon must access network resources for AI reviews and CI integration. The internal/daemon/service_render.go file handles baking proxy environment variables (HTTP_PROXY, HTTPS_PROXY, etc.) into the service definition, ensuring the daemon can reach external APIs regardless of how it was launched.

Practical Usage

To use the no-mistakes git proxy gate model, configure the proxy remote and push through it:

# Add the proxy remote (run once)

git remote add no-mistakes \
  "$(no-mistakes config get proxy-remote-url)"

# Push a committed branch through the gate

git push no-mistakes my-feature-branch

The daemon automatically takes over from this point, running the full pipeline before the code ever touches your upstream repository.

Summary

• The no-mistakes git proxy gate model installs a local Git remote that intercepts pushes before they reach upstream, ensuring every change passes validation.
• A background daemon in internal/daemon/lock.go manages exclusive access through an OS lock and creates isolated disposable worktrees in <NM_HOME>/worktrees.
• The validation pipeline in internal/pipeline/pipeline.go runs an eight-stage chain: intent, rebase, review, test, document, lint, push, PR, and CI.
• Gate findings in internal/pipeline/findings.go can park the pipeline, allowing developers to resolve issues or skip gates before the push continues.
• Only validated code reaches the upstream remote, ensuring every commit has been rebased, reviewed, tested, documented, and lint-checked.

Frequently Asked Questions

What happens if a gate fails in the no-mistakes pipeline?

When a gate fails or produces findings requiring attention, the daemon parks the pipeline at that specific gate. The developer receives structured output via the CLI or TUI and can choose to fix the issues, skip the gate, respond to AI review comments, or abort the entire push. The upstream repository remains untouched until the gate passes or the user aborts.

How does the no-mistakes daemon prevent concurrent push conflicts?

The daemon implements an exclusive OS lock mechanism in internal/daemon/lock.go that ensures only one daemon instance can operate on a given NM_HOME directory at a time. This prevents race conditions when multiple pushes occur simultaneously, serializing access to the disposable worktree cache and ensuring pipeline integrity.

Can I still push directly to origin while using the no-mistakes proxy?

While technically possible, direct pushes to origin bypass the validation gates entirely. The post-receive hook in internal/wizard/wizard.go validates that pushes come through the no-mistakes proxy remote. Direct pushes circumvent the AI-driven validation pipeline, defeating the purpose of the gate model and potentially introducing unvalidated code to the upstream repository.

Where does the no-mistakes daemon store its temporary worktrees?

The daemon creates disposable worktrees inside the <NM_HOME>/worktrees directory, where NM_HOME is the no-mistakes home directory (typically ~/.no-mistakes). As implemented in internal/git/git.go, these worktrees are completely isolated from the developer’s working directory and are cleaned up after the pipeline completes or fails, ensuring no contamination of the local workspace.

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