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

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 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, 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 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 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. 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 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 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, 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 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 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 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 implements a three-tier hierarchy: global defaults, repository-level .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. 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 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 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:

// 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:

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:

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:

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

Querying run metadata from the SQLite database:

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 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.

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