System Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• internal/engine/workflow/plan.go
• internal/engine/workflow/ship.go
• internal/integrations/codeintel/codeintel.go
• CONTRIBUTING.md
• internal/engine/workflow/prompts/base.md

M31 Autonomous (M31A) is a terminal-native AI coding agent designed to manage the entire software development lifecycle through a structured seven-phase workflow. Unlike simple autocomplete tools, M31A "owns the loop" by performing initial project analysis, planning multi-step implementations, executing code changes via a suite of specialized tools, and verifying the results through builds and tests before finalization.

The system is built as a static binary in Go, prioritizing zero telemetry and local execution. It leverages model arbitrage to optimize costs and provider fallback for reliability. The architecture is divided into a core workflow engine, a set of internal infrastructure packages for code intelligence and git operations, and a terminal user interface (TUI) powered by the Bubble Tea framework.

Sources: README.md:1-40, internal/engine/workflow/prompts/base.md:15-30

Core Workflow Engine

The M31A system operates through a sequential seven-phase state machine. This workflow ensures that every task is grounded in project context and verified for correctness.

Phase Descriptions

Phase	Responsibility	Key Components
Initialize	Project detection and code indexing.	internal/codeintel
Discuss	Gathering requirements through TUI questions.	internal/workflow/discuss.go
Plan	Task breakdown, dependency mapping, and security gating.	internal/engine/workflow/plan.go
Execute	Sequential task implementation using 18 tools.	internal/tools, pkg/taskrunner
Verify	Automated build/test cycles and error diagnosis.	internal/workflow/verify.go
Runtime	Dev server lifecycle and HTTP smoke tests.	internal/workflow/runtime.go
Ship	Final git commits, ledger updates, and walkthrough generation.	internal/engine/workflow/ship.go

Sources: README.md:118-144, internal/engine/workflow/prompts/base.md:25-45

Intelligence and Context Management

The architecture includes a sophisticated "Code Intelligence" layer that allows the agent to understand the codebase before making changes.

Code Intelligence (codeintel)

The Indexer in internal/integrations/codeintel/codeintel.go parses source files in Go, TypeScript, Python, and Rust. It builds an import graph and a symbol index to provide the LLM with relevant context.

• Import Graph: Tracks upstream and downstream dependencies for every file.
• Symbol Index: Maps function, type, and interface definitions across the project.
• Relevance Scorer: Ranks files based on their relationship to the user's goal.

Sources: internal/integrations/codeintel/codeintel.go:21-45, internal/integrations/codeintel/codeintel.go:280-320

Decision Logging and Learning

M31A maintains a "Learning Ledger" and "Decision Receipts." The system records architectural choices, rationale, and cost tracking into a markdown-backed ledger for cross-session recall.

Sources: README.md:160-175, internal/engine/workflow/ship.go:120-140

Execution Framework

Execution is handled by a specialized dispatcher that manages a suite of 18 tools.

Tool Dispatcher and Permissions

All filesystem and shell interactions are gated by a permission system and concurrency control.

• Topological Sort: Tasks are ordered using Kahn's algorithm to ensure dependencies are met before a dependent task starts.
• Bounded Parallelism: The system supports up to 4 concurrent tasks by default.
• Atomic Commits: One git commit is generated per task to facilitate rollback if verification fails.

Sources: README.md:180-200, CONTRIBUTING.md:40-60

Package Layout and Infrastructure

The project follows a strict internal/pkg separation. internal/ contains private implementation details, while pkg/ contains importable utilities.

Directory	Scope	Purpose
internal/workflow/	Internal	Core state machine and phase logic.
internal/provider/	Internal	Abstraction for OpenRouter, Zen, and Nvidia NIM.
internal/tools/	Internal	Implementations of the 18 built-in tools.
pkg/taskrunner/	Public	Kahn's algorithm implementation for task execution.
pkg/rollback/	Public	Git commit-chain management.
pkg/keychain/	Public	OS-native credential storage (Secret Service, Keychain, Credential Manager).

Sources: CONTRIBUTING.md:75-110, README.md:275-320

Security Layer

M31A implements multi-layered security to prevent unauthorized command execution or data leaks:

1. Permission Modal: Every Bash command requires user confirmation unless "allow always" is selected.
2. SSRF Protection: WebFetch blocks private and loopback IP addresses.
3. Credential Safety: API keys are never stored in plaintext on disk; they are held in the OS keychain.
4. Path Traversal Prevention: File tools are restricted to the working directory.

Sources: README.md:380-410, scripts/validate-release.sh:280-310

Conclusion

The M31 Autonomous architecture is a robust, security-first framework for AI-driven development. By decomposing the development process into seven distinct phases and grounding every action in a deep understanding of code intelligence, it provides a reliable and verifiable way to automate complex coding tasks from within the terminal.

Sources: README.md:460-480