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

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 for command parsing and 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 file contains the primary service logic, while manager.go handles run coordination and 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 file defines the common interface, while concrete implementations like claude.go and 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 file implements the core orchestration logic, while the steps/ subdirectory contains individual step implementations such as review.go and 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, 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 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 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, 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, 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, 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). 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

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

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)

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) 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) executes deterministic steps using a shared StepContext that carries configuration, database handles, and logging functions.
• Configuration (internal/config/config.go) and database (internal/db/db.go) modules provide persistent storage and settings management.
• Entry point is located at cmd/no-mistakes/main.go, which delegates to 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, which immediately delegates to the CLI package (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. 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 and provider-specific adapters in files like claude.go and 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, 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.

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