How to Run no-mistakes Locally: Complete Setup Guide

Running no-mistakes locally requires building the Go binary from source, initializing a gate repository with no-mistakes init, and pushing branches through the no-mistakes remote to trigger automated validation pipelines in disposable worktrees.

The no-mistakes project is a Go-based CLI tool that acts as a disposable git proxy, inserting a "gate" between your local repository and the remote to enforce quality checks. Available at kunchenguid/no-mistakes, this tool creates temporary worktrees to run linting, testing, and automatic fixes without polluting your working directory, pushing to upstream only after all checks pass.

Prerequisites and Building the Binary

Before running the tool locally, ensure you have Go 1.25 or later installed. The binary entry point resides in cmd/no-mistakes/main.go, which builds version information and initializes the command structure.

Clone the repository and build the binary:

git clone https://github.com/kunchenguid/no-mistakes.git
cd no-mistakes
make build

This generates ./bin/no-mistakes. Move it to your $PATH for global access:

sudo mv ./bin/no-mistakes /usr/local/bin/

The root command logic in internal/cli/root.go uses Cobra to register sub-commands including init, daemon, and axi.

Initializing the Gate Repository

The no-mistakes init command configures your local project to use the tool. Implemented in internal/cli/init.go, this command performs three critical actions:

1. Creates a gate repository under ~/.no-mistakes/repos/<hash>.git
2. Writes the local configuration file (.no-mistakes.yaml)
3. Installs the /no-mistakes skill for agent integration

Navigate to your project directory and run:

cd /path/to/your/project
no-mistakes init

The configuration loader in internal/config/config.go merges CLI flags, environment variables, and this repository-level configuration to determine pipeline behavior.

Running Pipelines Through the Gate

Once initialized, the standard workflow involves creating a branch, committing changes, and pushing through the gate remote:

git checkout -b feature/new-capability

# Edit files...

git commit -am "Add new capability"
git push no-mistakes feature/new-capability

When you push through the gate, the daemon—managed by internal/daemon/manager.go—creates a disposable worktree to execute the pipeline. The pipeline executor in internal/pipeline/executor.go orchestrates the sequence of steps including review, testing, linting, and documentation generation. Each step implementation lives under internal/pipeline/steps.

The tool abstracts platform-specific process groups through internal/daemon/service_* files, ensuring consistent behavior across macOS, Linux, and Windows.

Interactive TUI vs. Headless Execution

After pushing through the gate, you can interact with the run using the built-in TUI (Terminal User Interface):

no-mistakes

This attaches to the active run, presenting findings from the pipeline. The TUI renders the TOON axi interface defined in internal/cli/axi.go, which provides a non-interactive API that the daemon uses to drive execution. Press Enter to accept findings that require human judgment; safe fixes apply automatically.

For CI environments or automated agents, run headlessly without the TUI:

no-mistakes axi start --run-id <id>

You can also trigger the entire workflow from scratch without a prior push:

no-mistakes -y

This wizard creates a branch, commits current changes, pushes through the gate, and attaches to the run automatically.

Debugging and Manual Daemon Control

Normally, the CLI starts the daemon automatically in the background. For debugging or development purposes, you can manually control the daemon lifecycle:

no-mistakes daemon start &

The daemon will continue running in the background, watching for new gate pushes and managing worktree cleanup. Subsequent git push no-mistakes commands will be picked up by this manually started instance.

Summary

• Build the binary from cmd/no-mistakes/main.go using make build (requires Go 1.25).
• Initialize projects with no-mistakes init to create gate repositories under ~/.no-mistakes/repos/ and configure .no-mistakes.yaml.
• Push branches through git push no-mistakes <branch> to trigger disposable worktree pipelines managed by internal/daemon/manager.go.
• Interact via the TUI (no-mistakes) for human review or the axi API (no-mistakes axi start) for headless execution.
• Configure behavior through internal/config/config.go, which merges CLI flags, environment variables, and repository settings.

Frequently Asked Questions

What are the system requirements for running no-mistakes locally?

You need Go 1.25 or later to build from source. The daemon supports macOS, Linux, and Windows through platform-specific process group abstractions in internal/daemon/service_*. Pre-built binaries can also be installed directly to your $PATH without compilation.

Where does no-mistakes store its gate repositories?

The no-mistakes init command creates gate repositories under ~/.no-mistakes/repos/<hash>.git, where <hash> represents a unique identifier for your project. This location keeps the proxy repository separate from your working tree while allowing the daemon in internal/daemon/manager.go to manage disposable worktrees efficiently.

How do I run no-mistakes in a CI/CD pipeline without the interactive TUI?

Use the axi subcommand for headless execution. The axi interface in internal/cli/axi.go provides a non-interactive API that drives the pipeline without TUI rendering. Run no-mistakes axi start --run-id <id> to execute the same validation steps (lint, test, automatic fixes) that the interactive mode performs, making it suitable for automated agents and continuous integration environments.

Why does no-mistakes use disposable worktrees instead of modifying my working directory?

The pipeline executor in internal/pipeline/executor.go creates disposable worktrees to ensure your local working directory remains untouched during linting, testing, and automatic fixing. This isolation prevents partial states or failed fixes from corrupting your active development environment. Only after the pipeline succeeds does the tool push the validated branch to the configured upstream and optionally open a pull request.

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