How no-mistakes Integrates with AI Agents like Claude and Codex: A Complete Technical Guide

No-mistakes integrates with Claude and Codex through a pluggable Agent interface that spawns external binaries as subprocesses, streaming JSON-encoded requests and parsing structured responses via a unified factory pattern.

The open-source tool no-mistakes (kunchenguid/no-mistakes) provides a unified abstraction layer for orchestrating AI-powered development workflows. Understanding how no-mistakes integrates with AI agents like Claude and Codex reveals a sophisticated architecture based on interface-driven design and subprocess communication, allowing seamless swapping between different AI backends without changing core pipeline logic.

Architecture Overview

The Agent Interface and Factory Pattern

At the heart of the integration lies the Agent interface defined in internal/agent/agent.go. This interface abstracts any AI-backed tool through two core methods:

• Run(ctx, opts) (*Result, error) – Executes the agent with context and options
• Close() error – Cleans up resources

The factory pattern implemented via agent.New and agent.NewWithOptions in the same file creates concrete implementations based on the selected AgentName. This enum, defined in internal/types/types.go, enumerates supported backends including AgentClaude, AgentCodex, AgentRovoDev, AgentOpenCode, AgentPi, and custom ACP targets.

Configuration and Agent Resolution

Users select their preferred AI agent through ~/.no-mistakes/config.yaml or the --agent CLI flag. The configuration loader in internal/config/config.go resolves the agent name, validates it against the AgentName enum, and determines the binary path through either agent_path_override or auto-detection.

When the CLI in cmd/no-mistakes/main.go initializes, it wires the selected agent into each pipeline step (such as run, review, or fix), passing the resolved configuration to the step executor.

Concrete Agent Implementations

The repository provides specific implementations for each supported AI:

• claudeAgent in internal/agent/claude.go – Communicates with the Claude binary
• codexAgent in internal/agent/codex.go – Communicates with the Codex binary

Both implementations follow an identical execution model: they spawn the external binary as a subprocess using exec.CommandContext, pipe JSON-encoded requests to the process's standard input, stream the response through an OnChunk callback for real-time TUI updates, and parse the final output using parseStructuredTextOutput.

Data Flow and Communication Protocol

The integration between no-mistakes and AI agents follows a strict nine-step data flow:

1. Request initiation – The CLI receives a user prompt (e.g., no-mistakes run "Add unit tests")
2. Agent resolution – config.ResolveAgent selects the appropriate backend based on configuration hierarchy
3. Construction – agent.New(name, bin, extraArgs) instantiates either a claudeAgent or codexAgent
4. Subprocess creation – The Run method spawns the external binary with context-aware execution
5. Payload transmission – The system writes a JSON payload containing prompt, cwd, and optional JSON Schema to the agent's stdin
6. Streaming response – The agent implementation forwards output chunks to the OnChunk callback for live display
7. Output parsing – parseStructuredTextOutput extracts JSON from raw output, fenced code blocks (```json), or bare objects
8. Token accounting – The parser populates TokenUsage from the agent's usage line emission
9. Result consumption – The pipeline receives a Result struct containing structured JSON and raw text for downstream processing

Intent Readers and Transcript Replay

For scenarios requiring deterministic testing or replay of historical interactions, no-mistakes includes intent readers located in internal/intent/reader_claude.go and internal/intent/reader_codex.go.

These components locate existing transcripts stored in ~/.claude/projects/ or ~/.codex/projects/, filter them by the current working directory, and feed recorded messages into the pipeline as if they originated from a live agent session. This enables reproducible testing and debugging without incurring API costs.

Testing Infrastructure

The repository maintains a comprehensive testing harness through cmd/fakeagent/claude.go and cmd/fakeagent/codex.go. These lightweight "fake" binaries mimic the real CLI protocol of their respective agents, allowing unit tests and end-to-end fixtures to execute without external dependencies or API keys.

Implementation Examples

Selecting Claude via Configuration

# ~/.no-mistakes/config.yaml

agent: claude          # choose Claude as the default AI

agent_path_override:
  claude: /usr/local/bin/claude   # optional custom binary location

The config loader validates types.AgentClaude and passes the resolved path to agent.New.

Running with Explicit Agent Flag

no-mistakes run --agent codex "Refactor this function to be more idiomatic"

The CLI parses the flag, overrides the config value, creates a codexAgent, and streams the result.

Using the Go API

package main

import (
    "context"
    "log"

    "github.com/kunchenguid/no-mistakes/internal/agent"
    "github.com/kunchenguid/no-mistakes/internal/types"
)

func main() {
    // Build a Claude agent (binary path could be discovered automatically)
    claude, err := agent.New(types.AgentClaude, "/usr/local/bin/claude", nil)
    if err != nil {
        log.Fatalf("cannot create agent: %v", err)
    }
    defer claude.Close()

    // Run the agent
    res, err := claude.Run(context.Background(), agent.RunOpts{
        Prompt: "Write a Go function that returns the nth Fibonacci number.",
        CWD:    "/home/me/projects/demo",
    })
    if err != nil {
        log.Fatalf("agent failed: %v", err)
    }

    // `res.Output` contains structured JSON if the agent emitted one,
    // otherwise `res.Text` holds the raw generated code.
    log.Printf("Agent replied with %d bytes of text", len(res.Text))
}

Replaying a Recorded Transcript

package test

import (
    "testing"
    "github.com/kunchenguid/no-mistakes/internal/intent"
)

func TestReplayClaude(t *testing.T) {
    // Seed a minimal Claude transcript under a fake HOME.
    // The recorder is part of the e2e harness.
    seedClaudeTranscript(t, "/tmp/home", "/tmp/repo", "main.go")

    // Create a reader that will locate the transcript.
    r := intent.NewClaudeReader()
    msgs, err := r.ReadMessages("/tmp/repo")
    if err != nil {
        t.Fatalf("failed to read transcript: %v", err)
    }
    // `msgs` now contains the same messages that Claude would have produced.
    t.Logf("replayed %d messages", len(msgs))
}

Summary

• no-mistakes abstracts Claude and Codex behind a unified Agent interface defined in internal/agent/agent.go, enabling seamless backend swapping without pipeline modifications.
• The factory pattern in agent.New constructs concrete claudeAgent or codexAgent instances based on the AgentName enum from internal/types/types.go.
• Communication occurs via subprocess execution with JSON-encoded requests and streaming responses, parsed by parseStructuredTextOutput to handle both structured and raw text output.
• Configuration resolution in internal/config/config.go supports global config files, repository-specific settings, and CLI flags like --agent.
• Intent readers in internal/intent/ enable replay of historical transcripts from ~/.claude/projects/ or ~/.codex/projects/ for testing and debugging.
• The cmd/fakeagent/ package provides protocol-compliant test doubles for isolated unit testing.

Frequently Asked Questions

How do I configure no-mistakes to use Claude instead of Codex?

Set agent: claude in your ~/.no-mistakes/config.yaml file, or use the --agent claude flag when running CLI commands. The configuration loader in internal/config/config.go validates the selection against the AgentName enum and resolves the binary path through auto-detection or the agent_path_override map.

What is the Agent interface in no-mistakes?

The Agent interface is the core abstraction defined in internal/agent/agent.go that unifies all AI backend integrations. It requires implementing Run(ctx context.Context, opts RunOpts) (*Result, error) for execution and Close() error for resource cleanup. Both claudeAgent and codexAgent implement this interface, allowing the pipeline to treat different AI providers identically.

How does no-mistakes handle JSON responses from AI agents?

The system uses parseStructuredTextOutput in internal/agent/agent.go to extract JSON from agent output. This function handles three formats: raw JSON objects, fenced code blocks marked with ```json, and the last bare {} object in the output stream. The parsed data is validated against an optional JSON Schema supplied in RunOpts before being returned in the Result struct.

Can I replay existing Claude or Codex transcripts?

Yes. The intent reader system in internal/intent/reader_claude.go and internal/intent/reader_codex.go can locate and replay transcripts stored in ~/.claude/projects/ or ~/.codex/projects/. These readers filter transcripts by the current working directory and return parsed Message structs that feed into the pipeline as if they came from a live agent session, enabling deterministic testing and debugging.

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