# How to Run no-mistakes Locally: Complete Setup Guide

> Learn how to run no-mistakes locally with this complete setup guide. Build the Go binary, initialize a repository, and push branches to trigger automated validation pipelines.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/cmd/no-mistakes/main.go), which builds version information and initializes the command structure.

Clone the repository and build the binary:

```bash
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:

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

```

The root command logic in [`internal/cli/root.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml))
3. Installs the `/no-mistakes` skill for agent integration

Navigate to your project directory and run:

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

```

The configuration loader in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go)—creates a **disposable worktree** to execute the pipeline. The pipeline executor in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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):

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

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

```

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

```bash
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:

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml).
- **Push** branches through `git push no-mistakes <branch>` to trigger disposable worktree pipelines managed by [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.