# How the Core Modules of no-mistakes Are Organized: A Technical Deep Dive

> Explore the technical deep dive into how no-mistakes organizes its core modules. Learn about the ten distinct internal packages and their roles in user interaction, background processing, and AI coordination for clean code sepa...

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

---

**The no-mistakes codebase organizes functionality into ten distinct internal packages—CLI, Daemon, Agent adapters, Pipeline engine, Configuration, Database, Git helpers, Path management, Shell execution, and Wizard/TUI—each residing under the `internal/` directory to enforce clean separation of concerns between user interaction, background processing, and AI coordination.**

The **no-mistakes** repository (available at `kunchenguid/no-mistakes`) is a Go-based automation tool that validates code changes before they reach remote repositories. Understanding how its core modules are organized reveals a deliberate architecture that isolates CLI handling from long-running daemon processes and AI agent coordination.

## Overview of the Modular Architecture

All core modules live beneath the `internal/` directory, following Go’s standard project layout. This design choice prevents external packages from importing implementation details while clearly delineating responsibilities. The architecture moves data unidirectionally from user input through the daemon and pipeline, ultimately persisting results in SQLite.

## The Ten Core Modules Explained

### CLI (Command-Line Interface)

The **CLI** module parses user commands, launches the daemon, drives the interactive TUI, and forwards high-level actions to the pipeline. Located in `internal/cli`, it handles entry points such as `no-mistakes` or `git push no-mistakes`.

Key files include [`root.go`](https://github.com/kunchenguid/no-mistakes/blob/main/root.go) for command parsing and [`daemon_cmd.go`](https://github.com/kunchenguid/no-mistakes/blob/main/daemon_cmd.go) for push notification handling. The CLI remains thin, delegating actual work to the daemon rather than executing business logic directly.

### Daemon

The **Daemon** runs as a long-lived background service that receives push notifications, coordinates runs, and protects a singleton lock on `<NM_HOME>/daemon.lock`. Found in `internal/daemon`, it manages the lifecycle of validation jobs.

The [`daemon.go`](https://github.com/kunchenguid/no-mistakes/blob/main/daemon.go) file contains the primary service logic, while [`manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/manager.go) handles run coordination and [`lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/lock.go) ensures only one daemon instance operates per home directory. The daemon creates disposable worktrees and registers new runs before handing them to the pipeline engine.

### Agent Adapters

**Agent adapters** provide uniform wrappers around various AI agents (Claude, Codex, Copilot, Opencode, Pi, ACX). Located in `internal/agent`, these adapters handle session management, retries, environment handling, and fallback behavior.

The [`agent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/agent.go) file defines the common interface, while concrete implementations like [`claude.go`](https://github.com/kunchenguid/no-mistakes/blob/main/claude.go) and [`codex.go`](https://github.com/kunchenguid/no-mistakes/blob/main/codex.go) translate generic requests into provider-specific API calls. This abstraction allows the pipeline to invoke `RunAgentSession` without concerning itself with underlying provider differences.

### Pipeline Engine

The **Pipeline engine** orchestrates deterministic steps (review, rebase, lint, document, push, PR creation). Located in `internal/pipeline`, it provides a shared `StepContext` and mediates findings, auto-fixes, and approvals.

The [`pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/pipeline.go) file implements the core orchestration logic, while the `steps/` subdirectory contains individual step implementations such as [`review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/review.go) and [`push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/push.go). Each step receives the `StepContext` containing the selected agent, configuration, and database handle.

### Configuration

The **Configuration** module loads global and repository-specific settings (agent selection, skip-step options, intent handling, evidence rules). Implemented in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go), it merges configuration layers and provides typed access to settings.

### Database

The **Database** module persists run metadata, repo registration, step results, and lifecycle information in an SQLite file under `<NM_HOME>/db.sqlite`. The [`internal/db/db.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/db.go) file handles connection management and schema initialization.

### Git Helpers

**Git helpers** provide thin wrappers around Git commands, safe handling of bare repositories, and work-tree management. Located in `internal/git`, the [`env.go`](https://github.com/kunchenguid/no-mistakes/blob/main/env.go) file abstracts environment detection and repository state inspection.

### Path Management

The **Path management** module resolves `<NM_HOME>`, creates required directories, and abstracts filesystem layout. Implemented in [`internal/paths/paths.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/paths/paths.go), it ensures consistent path resolution across platforms.

### Shell Execution

**Shell execution** provides cross-platform, cancellable subprocess utilities including `ConfigureShellCommand` and `RunShellCommand`. Found in [`internal/shellenv/shell_command.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/shellenv/shell_command.go), these utilities guarantee proper cleanup of child processes even during interruption.

### Wizard / TUI

The **Wizard** module guides first-time users through repository initialization, branch creation, and push-through-gate flow. Located in [`internal/wizard/wizard.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/wizard/wizard.go), it provides interactive prompts for setup workflows.

## Architectural Data Flow

Understanding how the core modules interact clarifies the request lifecycle:

1. **User invokes the CLI** via `no-mistakes` or `git push no-mistakes`.
2. The CLI parses flags, loads configuration via `internal/config`, and opens the database via `internal/db`.
3. For push notifications, the CLI forwards the request to the **daemon** ([`daemon_cmd.go`](https://github.com/kunchenguid/no-mistakes/blob/main/daemon_cmd.go)). The daemon, guarded by a singleton lock, creates a disposable worktree, registers a new run, and hands it to the **pipeline engine**.
4. The pipeline builds a `StepContext` (including the chosen **agent** from `internal/agent`), then executes each step in order. Steps may invoke an AI agent (`RunAgentSession`), apply safe fixes, pause for user approval (`NeedsApproval`), or forward the branch to the configured remote.
5. Findings and outcomes are recorded in the **database**, displayed by the CLI/TUI, and optionally exported to the remote PR.

## Practical Integration Examples

### Starting the Daemon Manually

```go
package main

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

func main() {
	// Starts the daemon in the foreground; Ctrl‑C stops it.
	daemon.Start()
}

```

### Running a Single Pipeline Step Programmatically

```go
package main

import (
	"context"
	"github.com/kunchenguid/no-mistakes/internal/pipeline"
	"github.com/kunchenguid/no-mistakes/internal/pipeline/steps"
	"github.com/kunchenguid/no-mistakes/internal/config"
	"github.com/kunchenguid/no-mistakes/internal/db"
)

func main() {
	ctx := context.Background()
	cfg, _ := config.LoadGlobal()
	dbh, _ := db.Open("/tmp/no-mistakes-db.sqlite")

	sctx := &pipeline.StepContext{
		Ctx:    ctx,
		Config: cfg,
		DB:     dbh,
		Log:    func(s string) { println(s) },
	}
	// Run the lint step directly.
	outcome, _ := steps.NewLint().Execute(sctx)
	println("Lint exit code:", outcome.ExitCode)
}

```

### Using an Agent Directly (e.g., Claude)

```go
package main

import (
	"context"
	"github.com/kunchenguid/no-mistakes/internal/agent"
)

func main() {
	claude := agent.NewClaude()
	res, _ := claude.Run(context.Background(), agent.RunOpts{
		Prompt: "Summarize the intent of this change:",
	})
	println("Claude response:", res.Stdout)
}

```

## Summary

- The **no-mistakes** codebase organizes functionality into ten specialized modules under `internal/`, ensuring clear separation between CLI, daemon, and AI coordination.
- The **daemon** ([`internal/daemon/daemon.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/daemon.go)) maintains a singleton lock at `<NM_HOME>/daemon.lock` and coordinates background processing.
- **Agent adapters** (`internal/agent/`) abstract multiple AI providers behind a unified interface accessed via `RunAgentSession`.
- The **pipeline engine** ([`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go)) executes deterministic steps using a shared `StepContext` that carries configuration, database handles, and logging functions.
- **Configuration** ([`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go)) and **database** ([`internal/db/db.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/db.go)) modules provide persistent storage and settings management.
- **Entry point** is located at [`cmd/no-mistakes/main.go`](https://github.com/kunchenguid/no-mistakes/blob/main/cmd/no-mistakes/main.go), which delegates to [`internal/cli/root.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/root.go).

## Frequently Asked Questions

### What is the entry point of the no-mistakes application?

The application entry point resides at [`cmd/no-mistakes/main.go`](https://github.com/kunchenguid/no-mistakes/blob/main/cmd/no-mistakes/main.go), which immediately delegates to the CLI package ([`internal/cli/root.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/root.go)). This file initializes the command parser and dispatches to subcommands like the daemon launcher or wizard interface.

### How does the daemon prevent multiple instances from running?

The daemon uses a singleton lock mechanism implemented in [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go). It attempts to acquire an exclusive lock on the file `<NM_HOME>/daemon.lock`; if another process holds this lock, the new instance exits immediately, ensuring only one daemon manages the validation queue.

### Where are the AI agent implementations located?

AI agent implementations reside in `internal/agent/`, with the base interface defined in [`agent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/agent.go) and provider-specific adapters in files like [`claude.go`](https://github.com/kunchenguid/no-mistakes/blob/main/claude.go) and [`codex.go`](https://github.com/kunchenguid/no-mistakes/blob/main/codex.go). These adapters handle session management, retry logic, and environment-specific configuration for services including Claude, Codex, Copilot, Opencode, Pi, and ACX.

### How does the pipeline engine handle step execution?

The pipeline engine, defined in [`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go), constructs a `StepContext` containing the execution context, configuration, database handle, and logging function. It then iterates through steps (review, lint, push, etc.) located in `internal/pipeline/steps/`, each implementing an `Execute` method that returns outcomes and may request user approval via `NeedsApproval`.