Architecture of the no-mistakes Git Proxy: A Local Validation Pipeline Deep Dive

The no-mistakes git proxy is a local Git intermediary that intercepts pushes to a custom remote, spins up disposable work-trees to execute validation pipelines, and only forwards commits to the actual remote after all checks pass.

The kunchenguid/no-mistakes repository implements a sophisticated local Git proxy that acts as a gatekeeper between your working directory and the upstream repository. This architecture ensures that every commit undergoes rigorous validation—including rebasing, testing, linting, and documentation checks—before reaching the remote. Unlike traditional CI/CD that runs after push, this no-mistakes git proxy architecture validates code locally using temporary work-trees that leave your original checkout untouched.

Core Architectural Layers

The proxy splits functionality across five distinct layers, each handling specific responsibilities from command parsing to Git operations.

CLI Entry Point and Remote Interface

Built with the Cobra framework, the CLI serves as the Git remote interface. When you configure no-mistakes as a Git remote and execute git push no-mistakes, Git invokes the binary at internal/cli/root.go. This entry point parses the push command, initializes a run record, and triggers the validation pipeline while presenting itself to Git as a standard remote helper.

Pipeline Orchestration Layer

The internal/pipeline/pipeline.go file coordinates the execution of validation steps in strict sequence. It tracks run state in a local SQLite database, manages step transitions, and determines whether to continue execution, pause for user intervention when a finding occurs, or abort the entire operation. This orchestrator treats each validation phase as a discrete unit that must report success before the next begins.

Step Execution and Disposable Work-Trees

Individual validation steps reside in internal/pipeline/steps/ and include dedicated files like rebase.go, test.go, lint.go, and push.go. Each step operates within a disposable work-tree—a temporary Git workspace created by utilities in internal/git/git.go—ensuring your original repository remains untouched while subprocesses run commands like go test -race ./... or npm run lint. Steps can auto-fix safe issues, emit findings requiring user approval, or fail fast depending on severity.

Daemon and Background Process Management

For long-running operations and TUI attachment capabilities, internal/daemon/manager.go implements a persistent background service. This daemon manages work-tree-bound processes, handles cancellation requests, and maintains the interactive interface, allowing you to detach and re-attach to validation runs without losing state.

Persistent Storage with SQLite

The internal/db/run.go module provides a lightweight SQLite database that stores per-repository configuration, run metadata, findings, and timestamps. This persistence layer enables the proxy to resume interrupted runs and maintain state across CLI invocations, supporting the no-mistakes TUI for reviewing pending findings.

The Push Flow: From Local Branch to Remote

When you push to the no-mistakes remote, the architecture executes a rigorous validation chain:

1. Work-tree creation: The CLI spins up a disposable work-tree via internal/git/git.go, isolating validation from your working directory.
2. Pipeline initialization: A new run record is created in SQLite via internal/db/run.go, and the pipeline coordinator in internal/pipeline/pipeline.go begins sequential step execution.
3. Sequential validation: The system runs rebase → test → lint → docs → push, with each step executing in the temporary work-tree.
4. Finding handling: If a step produces a finding, the pipeline pauses, storing the state in SQLite until you approve, fix, or skip the issue via the TUI.
5. Remote push: Only after all steps report success does internal/pipeline/steps/push.go perform a lease-guarded push to the actual remote and optionally open a pull request.

Key Source Files and Implementation Details

Understanding the no-mistakes git proxy architecture requires familiarity with these specific implementation files:

• internal/cli/root.go: Entry point that implements the Git remote protocol and handles git push no-mistakes invocations.
• internal/cli/wizard.go: Run-attachment logic and interactive wizard for connecting to existing validation runs.
• internal/pipeline/pipeline.go: Central coordinator that manages step execution order and run state transitions.
• internal/pipeline/steps/rebase.go: Handles rebasing onto the remote-tracking branch within the disposable work-tree.
• internal/pipeline/steps/test.go: Executes test suites like go test -race ./... and reports results.
• internal/pipeline/steps/lint.go: Runs linting tools including go vet and custom skill-checks.
• internal/pipeline/steps/push.go: Performs the final lease-guarded force-push to the target remote.
• internal/daemon/manager.go: Background service for managing long-running processes and TUI sessions.
• internal/db/run.go: SQLite schema and queries for persisting run metadata and findings.
• internal/git/git.go: Low-level Git operations including repository root detection and work-tree management.

Summary

• The no-mistakes git proxy architecture intercepts pushes via a custom Git remote, acting as a local gatekeeper.
• Disposable work-trees in internal/git/git.go isolate validation from your working directory, ensuring safe experimentation.
• Pipeline orchestration in internal/pipeline/pipeline.go coordinates sequential validation steps (rebase, test, lint, docs, push).
• SQLite persistence via internal/db/run.go enables run resumption and finding management across sessions.
• Background daemon support in internal/daemon/manager.go handles long-running processes and TUI interactions.
• Only after all validation steps pass does the proxy forward commits to the actual remote using lease-guarded pushes.

Frequently Asked Questions

What is the no-mistakes git proxy?

The no-mistakes git proxy is a local CLI tool built with Cobra that functions as a Git remote intermediary. It intercepts pushes to a custom remote name (e.g., no-mistakes), validates the code through automated pipelines, and only forwards commits to the actual upstream repository after all checks pass, preventing broken code from entering the remote.

How does the disposable work-tree mechanism work?

When you push to the proxy, the system creates a temporary Git work-tree via utilities in internal/git/git.go. This isolated directory contains a copy of your branch where validation steps run destructive commands like rebasing or force-checkout without affecting your original working directory. Once validation completes, the disposable work-tree is cleaned up automatically.

What happens when a validation step fails?

If a step in internal/pipeline/steps/ encounters an issue, it emits a finding that gets stored in the SQLite database via internal/db/run.go. The pipeline pauses, allowing you to address the issue through the TUI by fixing the code, approving the finding, or skipping that specific check. The run resumes only after you explicitly handle the finding.

How does the proxy handle concurrent runs?

The daemon manager in internal/daemon/manager.go maintains a background service that tracks active runs in SQLite. This architecture prevents conflicts by managing work-tree-bound processes centrally and ensuring that only one validation pipeline operates per repository workspace at a time, though multiple repositories can run validations simultaneously.

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