Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
M31 Autonomous (M31A) is a terminal-native AI coding assistant designed to own the entire software development lifecycle. Unlike traditional autocomplete tools, M31A operates through a structured seven-phase workflow that includes planning, execution, verification, and shipping to a git tree. It is built in Go as a single static binary with zero telemetry, ensuring privacy and ease of deployment across POSIX shells.
Sources: README.md:15-32, internal/engine/workflow/prompts/base.md:9-13
Installation
M31A supports multiple installation methods across different operating systems. The tool is distributed as a static binary, requiring no external dependencies like Electron.
Quick Install
For Linux and macOS users, a one-liner installation script is available via curl.
curl -fsSL https://raw.githubusercontent.com/eshanized/M31A/master/install.sh | bash
Sources: README.md:47-48, install.sh
Package Managers
| Platform | Method | Command |
|---|---|---|
| macOS | Homebrew | brew install eshanized/tap/m31a |
| Windows | Scoop | scoop install m31a |
| Linux | Binary | Download .deb, .rpm, or .apk from GitHub Releases |
Sources: README.md:39-45
Building from Source
M31A requires Go 1.22+ (or Go 1.25+ for development) and must be built with CGO_ENABLED=0 to maintain its static binary nature.
git clone https://github.com/eshanized/M31A.git
cd M31A
CGO_ENABLED=0 go build -o m31a ./cmd/m31a
Sources: README.md:50-54, CONTRIBUTING.md:10-15, scripts/verify_v1.sh:31
Initial Configuration
On the first launch, M31A guides the user through the setup of API providers. The system supports three primary gateways: OpenRouter, Zen, and Nvidia NIM.
- API Keys: M31A will prompt for your OpenRouter, Zen, or Nvidia API key.
- Key Storage: Keys are stored securely in the OS keychain (Linux Secret Service, macOS Keychain, or Windows Credential Manager). They are never written to disk in plaintext.
- Provider Fallback: If a primary provider degrades, the system automatically falls back to secondary providers as defined in the configuration.
Sources: README.md:56-58, README.md:179-183, scripts/validate-release.sh:220-225
Core Workflow
M31A operates using a sequential seven-phase engine. This structured approach ensures that code is not just suggested, but planned and verified before being committed.
The diagram shows the standard progression of a coding task from detection to final git commit.
Sources: internal/engine/workflow/prompts/base.md:17-26, README.md:100-112
Workflow Phases Summary
| Phase | Purpose |
|---|---|
| Initialize | Detects project type and initializes git repository. |
| Discuss | Asks clarifying questions to understand requirements. |
| Plan | Generates a task list and proposed changes for user review. |
| Execute | Implements tasks sequentially using 18 built-in tools. |
| Verify | Validates output through syntax checks and tests. |
| Runtime | Manages dev server lifecycle and smoke tests. |
| Ship | Generates a walkthrough and commits verified changes. |
Sources: internal/engine/workflow/prompts/base.md:17-26, README.md:126-140
Basic Usage
M31A can be used interactively through its TUI or via headless mode for automated tasks.
Interactive Mode (TUI)
Simply run m31a in your terminal to enter the Bubble Tea-based interface. You can provide a prompt directly in the REPL:
> refactor the auth middleware to use JWT
Sources: README.md:27-35
Headless Mode
For single prompts or full workflow execution without the interface:
# Single prompt
m31a --prompt "What files are in the project?"
# Full execution
m31a --goal "Create a REST API with authentication"
Sources: README.md:231-237
Development Environment Setup
For contributors looking to build or test M31A, the following tools are recommended:
- Go Version: 1.25+ is preferred for development.
- Static Builds: Always ensure
CGO_ENABLED=0to avoid dynamic linking. - Verification: Use the provided scripts to ensure release readiness.
make check: Runs fmt, tidy, vet, and tests../scripts/verify_v1.sh: Validates acceptance criteria../scripts/validate-release.sh: Performs cross-platform build validation.
Sources: CONTRIBUTING.md:7-9, scripts/verify_v1.sh:3-10, scripts/validate-release.sh:1-10
M31 Autonomous provides a comprehensive, secure, and terminal-native environment for building software. By following the seven-phase workflow and utilizing secure keychain storage, it ensures that AI-assisted coding is both productive and safe for production environments.