# Key Modules in the no-mistakes Project: Complete Architecture Guide

> Explore the key modules within the no-mistakes project. Our architecture guide details the fifteen Go packages managing CLI parsing, daemon orchestration, LLM integration, and Git pipeline execution for robust development.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: architecture
- Published: 2026-07-20

---

**The no-mistakes codebase organizes functionality into fifteen specialized Go packages under `internal/` that collectively manage CLI parsing, daemon orchestration, LLM agent integration, and Git-aware pipeline execution.**

The no-mistakes repository (kunchenguid/no-mistakes) implements a crash-resilient CI/CD system that orchestrates LLM agents while enforcing strict safety guarantees around user code. Understanding the key modules in the no-mistakes project reveals how the architecture separates concerns between user interaction, background execution, and external system integration.

## Entry Point and Command Interface

The user-facing surface of no-mistakes consists of three coordinated modules that handle argument parsing, command routing, and optional interactive visualization.

### Main Binary (`cmd/no-mistakes`)

The entry point at [`cmd/no-mistakes/main.go`](https://github.com/kunchenguid/no-mistakes/blob/main/cmd/no-mistakes/main.go) wires the entire application together. The `ExecuteRoot` function instantiates the CLI and handles top-level error propagation. This package serves as the composition root, importing capabilities from all other `internal/` packages without containing business logic itself.

### Command-Line Interface (`internal/cli`)

Located in [`internal/cli/cli.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/cli.go), this module defines the **AXI** sub-command structure (`axi run`, `axi status`, `axi sync`). Key types include `RootCmd`, `RunCmd`, and `SyncCmd`, which parse flags and dispatch to the appropriate handlers. The CLI acts as a thin client that either executes local operations directly or issues RPC calls to the background daemon via the IPC layer.

### Terminal User Interface (`internal/tui`)

The optional interactive mode implemented in [`internal/tui/tui.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/tui.go) provides real-time visualization of pipeline runs. The `TUI` type renders live logs and branch-sync status through `RenderRun`, while `HandleKeyEvents` manages user input for aborting or inspecting active operations.

## Core Execution Engine

Three modules manage the lifecycle of long-running processes and pipeline coordination, ensuring crash recovery and preventing unsafe termination.

### Background Daemon (`internal/daemon`)

The [`internal/daemon/daemon.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/daemon.go) file implements the singleton daemon process that orchestrates all background work. The `RunWithOptions` function initializes the daemon with a context-aware shutdown mechanism, while `daemonLock` enforces single-instance semantics across the system. The `RecoverStaleRuns` function automatically resumes interrupted pipelines after unexpected crashes, ensuring no work is lost between restarts.

### Pipeline Executor (`internal/pipeline`)

The heart of the execution logic resides in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go). The `Executor` type constructs directed graphs of **steps** (intent → review → test → lint → document → push) and manages their execution through `RunPipeline`. The module implements `SessionReuse` to maintain state across related operations and uses `StepContext` to propagate cancellation signals and timeouts through the step chain.

### Lifecycle Guards (`internal/lifecycle`)

Safety-critical operations in [`internal/lifecycle/guard.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/lifecycle/guard.go) prevent destructive actions while work is active. The `Guard` type uses `CheckActiveRuns` to block daemon shutdown or restart requests when pipelines are pending, with `ForceOverride` available for administrative recovery scenarios.

## External System Integration

Four specialized modules abstract interactions with Git repositories, LLM providers, and the underlying operating system.

### LLM Agent Adapters (`internal/agent`)

The [`internal/agent/agent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/agent.go) file defines a unified **Agent** interface that abstracts multiple LLM backends. Concrete implementations include `CodexAdapter` and `ClaudeAdapter`, each handling provider-specific binary invocation and JSON output parsing. The `InvokeAgent` method standardizes request formatting across different models, allowing the pipeline to switch providers without changing consumer code.

### Git Operations (`internal/git`)

Safe Git manipulation is encapsulated in [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go), which respects the *bare gate repository* mode required by no-mistakes. Functions like `WorktreeAdd` and `WorktreeRemove` automatically inject `--git-dir` flags through `SafeGitDir`, preventing accidental operations on the wrong repository state. The `Run` function provides a context-aware wrapper around Git commands with proper timeout handling.

### Branch Synchronization (`internal/branchsync`)

The [`internal/branchsync/sync.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/branchsync/sync.go) module implements the algorithm that keeps local worktrees synchronized with the daemon-managed gate branch. The `Sync` method handles fast-forward merges, diverged history recovery, and guarded move operations. The `Recover` function specifically addresses crash scenarios where the worktree was left in an inconsistent state.

### Shell Environment (`internal/shellenv`)

Subprocess management in [`internal/shellenv/shellenv.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/shellenv/shellenv.go) provides secure, cancellable command execution. The `ShellCommand` type configures execution contexts through `ConfigureShellCommand`, while `RunShellCommand` implements proper Windows console hardening and Unix signal forwarding. All commands respect `context.Context` cancellation for immediate termination when pipelines are aborted.

## Infrastructure and Communication

Four modules handle cross-cutting concerns including configuration, persistence, and inter-process communication.

### Inter-Process Communication (`internal/ipc`)

The [`internal/ipc/protocol.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/ipc/protocol.go) file defines the RPC layer connecting CLI clients to the daemon. The `Client` and `Server` types communicate over Unix sockets (or Windows named pipes via the `Transport` abstraction). Standard commands include `CallStatus` for health checks and abort signals, with the `Protocol` type ensuring message serialization consistency.

### Configuration Management (`internal/config`)

Configuration loading in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) implements a three-tier hierarchy: global defaults, repository-level [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml), and command-line overrides. The `LoadConfig` function enforces trust boundaries through `RepoTrustedConfig`, ensuring that arbitrary commands can only be read from the repository's default trusted branch. `ValidateConfig` performs schema validation and dependency checking between configuration sections.

### Database Persistence (`internal/db`)

Run metadata and telemetry are stored in SQLite via [`internal/db/db.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/db.go). The `OpenDB` function initializes the database at `<NM_HOME>/db.sqlite`, with `Migrate` handling schema versioning. Core entities include `RunRecord` for pipeline executions and `AgentInvocation` for LLM call tracking, providing crash-recovery capabilities and historical audit trails.

## Shared Utilities

Two foundational modules provide common functionality used across all other packages.

### Path Resolution (`internal/paths`)

The [`internal/paths/paths.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/paths/paths.go) module centralizes filesystem operations through `CreateDir` and `JoinPath`, ensuring consistent permission bits (typically 0750) and symlink normalization. The `ResolveNMHome` function determines the active home directory from environment variables with sensible defaults.

### Core Types (`internal/types`)

Shared data structures defined in [`internal/types/types.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/types/types.go) include `RunStatus` (enum for pending/running/completed/failed states), `Finding` (structured representation of LLM outputs), and `IntentSource` (classification of code change origins). Centralizing these definitions prevents circular dependencies and ensures type safety across package boundaries.

## Code Examples

The following snippets demonstrate typical usage patterns for the key modules.

Initializing and running the CLI entry point:

```go
// In cmd/no-mistakes/main.go
func main() {
    root := cli.NewRootCmd() // internal/cli
    if err := root.Execute(); err != nil { 
        log.Fatal(err) 
    }
}

```

Starting the daemon programmatically with recovery options:

```go
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
opts := daemon.Options{Root: "/path/to/gate"}
if err := daemon.RunWithOptions(ctx, opts); err != nil { 
    log.Fatalf("daemon failed: %v", err) 
}

```

Creating a pipeline executor and starting a run:

```go
cfg, _ := config.LoadConfig(".")
exec := pipeline.NewExecutor(cfg) // internal/pipeline
runID, err := exec.StartRun(context.Background(), "my-branch")

```

Invoking an LLM agent through the adapter interface:

```go
agent := agent.NewCodexAdapter()
resp, err := agent.Invoke(context.Background(), "Review the following diff…")

```

Querying run metadata from the SQLite database:

```go
db, _ := db.Open("$NM_HOME/db.sqlite")
run, _ := db.GetRun(runID)
fmt.Printf("Run %d status: %s\n", run.ID, run.Status)

```

## Summary

- **The no-mistakes project** organizes code into fifteen specialized modules under `internal/` and `cmd/`, following strict separation of concerns between CLI, daemon, and infrastructure layers.
- **Execution flow** moves from `internal/cli` through `internal/ipc` to `internal/daemon`, which coordinates `internal/pipeline` execution using `internal/agent` and `internal/git` adapters.
- **Safety mechanisms** include `internal/lifecycle` guards preventing shutdown during active runs, `internal/branchsync` ensuring Git consistency, and `internal/db` providing crash-recovery through SQLite persistence.
- **Configuration and paths** are centralized in `internal/config` and `internal/paths`, enforcing trust boundaries and consistent filesystem operations across all modules.

## Frequently Asked Questions

### How does the CLI communicate with the background daemon?

The CLI uses the `internal/ipc` module to establish RPC connections over Unix sockets (or Windows named pipes). The `Client` type in [`internal/ipc/protocol.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/ipc/protocol.go) provides methods like `CallStatus` that serialize commands and transmit them to the daemon's `Server`, enabling remote orchestration without direct process coupling.

### What prevents data loss if the daemon crashes during a pipeline run?

The `internal/daemon` module implements `RecoverStaleRuns` to detect interrupted operations on startup, while `internal/db` persists run states and agent invocations to SQLite. When the daemon restarts, it queries the database through `RunRecord` entries to resume or properly terminate incomplete pipelines.

### How does no-mistakes support multiple LLM providers simultaneously?

The `internal/agent` module defines a unified `Agent` interface with provider-specific adapters like `CodexAdapter` and `ClaudeAdapter`. Each adapter implements `InvokeAgent` to handle binary-specific invocation and JSON parsing, allowing the `internal/pipeline` executor to switch between Codex, Claude, or other models through configuration changes alone.

### Where does no-mistakes store its configuration and runtime data?

Configuration is loaded by `internal/config` from three sources: global defaults, repository-level config files, and command-line flags, with validation ensuring trusted sources. Runtime data including the SQLite database is stored under the directory specified by `NM_HOME`, resolved through `internal/paths/ResolveNMHome` with proper permission enforcement.