DOCSEARCHbyAlgolia
Submit Docs

no-mistakes

repository·main·Indexed 24 days ago

https://github.com/kunchenguid/no-mistakes

A local git proxy that acts as a quality gate for pull requests. It intercepts git pushes and runs them through an AI-driven validation pipeline (review, test, docs, lint) in an isolated worktree, forwarding code to the remote only after checks pass and are approved. Features include a Terminal User Interface (TUI) for reviewing findings, an auto-fix loop for mechanical issues, and integration as an agent skill for coding assistants like Claude Code.

Tokens
36K
Snippets
71
Records
271
Agent score
93%

What's inside no-mistakes

  1. Understand the no-mistakes pipeline flow

    main

    The no-mistakes validation pipeline follows a specific sequence of steps to ensure code quality and correctness before pushing. The standard execution order is:

    intent → rebase → review → test → document → lint → push → pr → ci

    Each step can produce findings, request approval, trigger auto-fixes, or apply safe fixes. Fatal errors in any step will stop the entire pipeline. Steps can be pre-skipped, skipped by the user, or skipped automatically by the pipeline logic.

  2. Scope and Integration Boundaries

    main

    It is important to distinguish no-mistakes from other parts of the development lifecycle:

    • Local Tooling: no-mistakes is a local tool that runs on the user's machine under their identity. It is not a CI system, agent orchestrator, or code host.
    • CI vs. Gate: While no-mistakes acts as a local gate, CI remains the shared outer gate for the team, and merge policies are managed by the code host provider.
    • Agent Agnostic: The gate is designed to work with any coding agent (human or AI) and does not lock the user into a specific model or vendor.

  3. Understand the no-mistakes mental model

    main

    no-mistakes acts as a local git proxy that sits between your local repository and your remote (e.g., origin). Instead of pushing directly to your main remote, you push to a no-mistakes remote. This triggers an AI-driven validation pipeline in a disposable worktree that does not touch your active working directory.

    The pipeline follows a fixed order: intent → rebase → review → test → document → lint → push → pr → ci.

    Key characteristics:

    • Non-destructive: origin is never hijacked; git push origin behaves normally.
    • Disposable: All validation runs in a separate worktree so you can continue coding.
    • Gated: The branch only reaches the final push target after all checks pass or are manually approved/skipped.

  4. Understand the core concept of the no-mistakes gate

    main

    no-mistakes provides a single, explicit gate between a local branch and a configured push target.

    Key operational principles:

    • Explicit Consent: The gate is triggered by pushing to a specific, named remote. This push acts as the consent boundary for the tool to validate, apply fixes, push the branch, and raise a PR.
    • Fixed Pipeline: The shape and order of the pipeline are fixed to ensure that "passed the gate" has a consistent meaning across all repositories.
    • No Silent Degradation: If a step cannot run, the gate refuses the operation loudly rather than skipping the check or degrading to a weaker validation.
    • Safety First: The tool is designed to never lose code (author commits, target commits, or pipeline-generated fixes). If safety cannot be verified, the push is refused.
    • Human-in-the-loop: The tool handles mechanical validation and objective fixes, but human judgment is required for intent and merge decisions. Changes that contradict author intent are parked for a decision rather than auto-resolved.

  5. Understand the no-mistakes Pipeline sequence

    main

    The no-mistakes pipeline runs a fixed, opinionated sequence of nine steps to ensure a branch is validated before pushing. The order of these steps is not configurable. The sequence is:

    1. Intent: Uses supplied intent or infers it from recent local agent transcripts.
    2. Rebase: Fetches fresh remote upstream and the configured branch target, then rebases your branch onto them.
    3. Review: AI code review of your diff.
    4. Test: Targeted local validation of the change and intent (not a full CI suite).
    5. Document: Updates documentation and reports unresolved gaps.
    6. Lint: Runs lint/static analysis.
    7. Push: Safely pushes the validated branch to the configured target.
    8. PR: Creates or updates the pull request.
    9. CI: Watches CI + mergeability and auto-fixes failures.

    For detailed behavior, skip rules, and fix-commit formats for each step, refer to the Pipeline Steps documentation.

  6. Understand the no-mistakes pipeline

    main

    no-mistakes is a local gate that validates code changes through a multi-stage pipeline before they reach a configured push target. The pipeline includes:

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

    You interact with the pipeline using the no-mistakes axi command family. These commands output machine-readable TOON to stdout and progress information to stderr.

  7. Install no-mistakes on macOS or Linux

    main

    Run the installer script via curl. The installer places the binary in ~/.no-mistakes/bin and creates a symlink in ~/.local/bin or /usr/local/bin. It also automatically attempts to install or refresh the background daemon using launchd (macOS) or systemd (Linux).

    Telemetry Configuration: Official release binaries include default self-hosted telemetry. You can:

    • Disable telemetry: Set NO_MISTAKES_TELEMETRY=0.
    • Override host: Set NO_MISTAKES_UMAMI_HOST.
    • Override website ID: Set NO_MISTAKES_UMAMI_WEBSITE_ID.
    curl -fsSL https://raw.githubusercontent.com/kunchenguid/no-mistakes/main/docs/install.sh | sh

  8. Initialize no-mistakes in a repository

    main

    Run no-mistakes init to initialize the gate in your current repository. This creates a local git proxy that intercepts pushes to no-mistakes and routes them through an AI-driven validation pipeline (review → test → docs → lint) before forwarding to your remote.

    GitHub Fork Configuration: If you are contributing to a GitHub fork, keep your origin pointed at the parent repository and initialize using the --fork-url flag:

    no-mistakes init --fork-url <your-fork-url>
    no-mistakes init

  9. Uninstall no-mistakes

    main

    To completely remove no-mistakes, stop the daemon, delete the binary, and clear the state files.

    Steps:

    1. Stop the daemon: no-mistakes daemon stop.
    2. Remove the binary: rm -f ~/.local/bin/no-mistakes or /usr/local/bin/no-mistakes.
    3. Remove state: rm -rf ~/.no-mistakes.

    Platform-specific cleanup:

    • macOS: Remove ~/Library/LaunchAgents/com.kunchenguid.no-mistakes.daemon.*.plist.
    • Linux: Remove ~/.config/systemd/user/no-mistakes-daemon-*.service.
    • Windows: Remove the no-mistakes-daemon-* Task Scheduler task.
    no-mistakes daemon stop
rm -f ~/.local/bin/no-mistakes /usr/local/bin/no-mistakes
rm -rf ~/.no-mistakes

  10. Install no-mistakes via shell script

    main

    Use the following one-liner to install no-mistakes on macOS or Linux. The installer places the binary in ~/.no-mistakes/bin, links it into ~/.local/bin or /usr/local/bin, and restarts the background daemon.

    Telemetry Configuration

    Official release binaries include default self-hosted telemetry. You can manage this using environment variables:

    • Disable telemetry: NO_MISTAKES_TELEMETRY=0
    • Override Umami host: NO_MISTAKES_UMAMI_HOST
    • Override Umami website ID: NO_MISTAKES_UMAMI_WEBSITE_ID
    curl -fsSL https://raw.githubusercontent.com/kunchenguid/no-mistakes/main/docs/install.sh | sh

  11. Understand the Push pipeline step behavior

    main

    The Push step automatically pushes the validated branch to the configured target after all previous steps (Review, Test, Document, Lint) have passed. It requires no manual approval.

    Key Behaviors:

    • Formatting: If commands.format is set, it runs before the push.
    • Artifacts: It stages in-repo test evidence if test.evidence.store_in_repo is enabled.
    • Commits: It commits any uncommitted agent changes with the message no-mistakes: apply agent fixes.
    • Safety Checks:
      • It reloads the review-approved commit immediately before mutation and refuses to push if the binding is missing or invalid.
      • It refuses to force-push if the remote contains commits not incorporated by the current patch-id.
      • It uses --force-with-lease=<ref>:<sha> with an explicit SHA anchor for allowed rewrites.
      • It pushes the exact verified commit SHA rather than the mutable HEAD.
    • Routing: Supports GitHub fork routing via repos.fork_url.

  12. Perform actions on paused pipeline steps

    main

    When a step is awaiting approval (indicated by the ⏸ icon in the Pipeline box), use the following actions to advance the pipeline:

    KeyActionDescription
    aApproveContinue to the next step.
    fFixSend currently selected findings to the agent for fixing.
    sSkipSkip the current step and continue.
    xAbortAbort the run (requires pressing twice to confirm).
    oOpen PROpen the Pull Request URL in your browser.
    yYolo ModeToggle 'Yolo mode' to automatically resolve paused steps. It selects all findings, applies fixes, and approves gates.
    rRerunStart a new run after a failed or cancelled run.