What Is no-mistakes axi? The Agent-Facing CLI for Validation Pipelines

no-mistakes axi is the command-line interface that exposes the no-mistakes validation pipeline to users and AI agents, providing sub-commands to start runs, inspect status, respond to gates, and abort workflows.

The kunchenguid/no-mistakes repository provides an automated validation framework for software projects. The no-mistakes axi command family serves as the primary surface for driving the pipeline from the terminal, enabling both human users and autonomous agents to execute validation runs and make decisions at approval gates.

Architecture of the no-mistakes axi Command Family

The axi interface consists of a thin CLI layer that maps synchronous commands onto an asynchronous pipeline executor. The architecture separates the user-facing command surface from the internal daemon that manages repository state.

Skill Description and CLI Entry Point

The canonical definition of the command family resides in internal/skill/skill.go, where the Name and Description constants (lines 13-20) establish the single source of truth for the skill's identity. The CLI dispatcher in cmd/no-mistakes/main.go parses incoming axi sub-commands and routes them to the appropriate internal handlers.

Core Sub-commands

The axi surface exposes six primary operations:

• home: Displays the current branch, active runs, and next steps by re-using the skill description
• run: Initiates a validation run for the current HEAD and blocks until the first gate
• status: Retrieves the current run state from the database, including awaiting_agent flags
• respond: Supplies answers to parked gates using actions like approve, fix, or skip
• abort: Cancels in-flight runs by ID or current branch, cleaning up the worktree
• logs: Streams raw output from specific pipeline steps for debugging

How the no-mistakes axi Pipeline Works

When you initiate a validation workflow, the axi commands coordinate with the internal executor to manage state transitions and gate handling.

Starting a Run with axi run

The axi run command validates prerequisites, records user intent, and creates a run record in the database. According to internal/skill/skill.go (lines 96-115), the command blocks until the first gate or final outcome, ensuring synchronous feedback while the executor works asynchronously.

Gate Handling and the Parking Mechanism

When a step reaches a gate, the executor in internal/pipeline/executor.go (lines 50-56) marks the run as awaiting agent by calling SetRunAwaitingAgent in internal/db/run.go. This creates the awaiting_agent: parked <duration> state visible through axi status, indicating the pipeline pauses for human or agent input.

Responding to Gates with axi respond

The axi respond command writes user decisions to the database, allowing the executor to continue. As implemented in internal/skill/skill.go (lines 71-80), you specify an action (approve, fix, or skip) and optionally provide findings or instructions. The executor reads this response and resumes the pipeline.

Practical Usage Examples

The following terminal commands demonstrate a complete no-mistakes axi workflow, from initial inspection through gate resolution:

# Check the home view for current branch and run status

no-mistakes axi

# Start a validation run with explicit intent

no-mistakes axi run --intent "add a feature flag to the config loader"

# When the run pauses at a gate, check status

no-mistakes axi status

# Respond to the gate with your decision

no-mistakes axi respond --action approve

# Alternatively, fix specific findings

no-mistakes axi respond --action fix --findings 12,15 --instructions "use safe defaults"

# Stream logs from a specific step

no-mistakes axi logs --step review --full

# Abort the current run if needed

no-mistakes axi abort

Telemetry and Observability

The axi interface includes telemetry controls to prevent backend spam. As defined in internal/telemetry/readgate.go (lines 16-23), read-surface events like axi-status and axi-home are throttled, ensuring that frequent status checks do not overwhelm the telemetry pipeline.

Key Source Files

• internal/skill/skill.go: Central definition of the axi command family, description constants, and user-facing documentation
• cmd/no-mistakes/main.go: CLI entry point that routes axi sub-commands to internal handlers
• internal/pipeline/executor.go: Core executor that runs steps, pauses at gates, and records the awaiting_agent marker
• internal/db/run.go: Database layer containing SetRunAwaitingAgent for persisting parked states
• internal/telemetry/readgate.go: Throttling logic for axi-status and axi-home telemetry events
• internal/e2e/axi_journey_test.go: End-to-end test demonstrating full axi workflows from home to final outcome

Summary

• no-mistakes axi provides a synchronous CLI surface for an asynchronous validation pipeline
• The command family includes home, run, status, respond, abort, and logs sub-commands
• Runs pause at gates with an awaiting_agent flag set by the executor in internal/pipeline/executor.go
• Users resume pipelines via axi respond with actions like approve, fix, or skip
• Telemetry throttling in internal/telemetry/readgate.go prevents status check spam
• The skill definition in internal/skill/skill.go serves as the single source of truth for command behavior

Frequently Asked Questions

What does the axi command do in no-mistakes?

The axi command in the no-mistakes repository provides the agent-facing interface for driving validation pipelines. It allows users and AI agents to start validation runs (axi run), check current status (axi status), respond to approval gates (axi respond), and stream logs (axi logs), serving as the primary interaction surface with the underlying pipeline executor.

How do I respond to a gate in no-mistakes axi?

When a run pauses at a gate, use no-mistakes axi respond --action <choice> where <choice> is one of approve, fix, or skip. According to internal/skill/skill.go, you can optionally specify --findings IDs and --instructions to guide auto-fixes. The command writes your response to the database, causing the executor in internal/pipeline/executor.go to resume processing.

Where is the axi command family defined in the source code?

The canonical definition resides in internal/skill/skill.go, specifically in the Name and Description constants (lines 13-20). The CLI dispatcher that routes sub-commands is located in cmd/no-mistakes/main.go, while the execution logic that handles gates and parking states lives in internal/pipeline/executor.go.

How does no-mistakes axi handle telemetry?

Read-surface commands like axi status and axi home are subject to throttling defined in internal/telemetry/readgate.go (lines 16-23). This prevents excessive telemetry events when users or scripts frequently poll for status updates, ensuring the telemetry backend receives only meaningful state changes rather than duplicate read operations.

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