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

> Learn how no-mistakes integrates with AI agents like Claude and Codex using its pluggable interface. This guide details subprocess spawning and JSON streaming for powerful AI interactions.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: deep-dive
- Published: 2026-06-25

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/claude.go) – Communicates with the Claude binary
- **`codexAgent`** in [`internal/agent/codex.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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

```yaml

# ~/.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

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

```go
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

```go
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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/intent/reader_claude.go) and [`internal/intent/reader_codex.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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.