m1-m2-agent — Cost-Aware Hierarchical Coding Agent & Context Firewall

Empower any Frontier Coding Agent (Antigravity, Cursor, Claude Code, Cline, Windsurf) with an autonomous, cost-efficient M2 worker agent and context firewall.
Cut LLM token costs by up to 92% while keeping your frontier reasoning context 100% pristine.

💡 The Core Philosophy: The Human-Agent Analogy

In modern software development, a senior human engineer never manually reads 50,000 lines of raw compiler logs or scans 1,000 files by hand when an AI coding agent can do it.

• The Human Engineer operates at the high cognitive tier: planning architecture, evaluating trade-offs, formulating hypotheses, and reviewing results.
• The Coding Agent operates at the implementation tier: searching directories, parsing AST symbols, executing tests, and writing code.

m1-m2-agent brings this exact division of labor to AI Coding Agents:

• M1 (The Frontier Reasoner / Orchestrator): Powered by flagship models (Gemini 1.5 Pro, Claude 3.5 Sonnet, GPT-4o), M1 acts like the human software architect—focusing on strategy, architecture, and high-ambiguity decisions.
• M2 (The Cheap Worker Agent & Context Firewall): Powered by fast, affordable models (Gemini Flash, DeepSeek V4-Flash, Claude Haiku, Local Ollama/Qwen), M2 acts as the autonomous coding agent for M1—executing multi-turn tool loops, searches, and test suites, compressing outputs (80–98% CCR) and returning structured evidence.

⚡ Quickstart

1. Install via pip

pip install m1-m2-agent

2. Drop into Any Project (30 seconds)

cd /path/to/your/project
m2 init

m2 init interactively configures your model and API key via LiteLLM, generates cognitive rule files (AGENTS.md, .cursorrules, CLAUDE.md, .continuerules), and displays the plug-and-play MCP configuration.

3. Connect to Your IDE / Agent

Add to your IDE's MCP settings (.cursor/mcp.json, Antigravity settings, Claude Code, Cline, etc.):

{
  "mcpServers": {
    "m2-worker-agent": {
      "command": "m2-mcp-server",
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}

🤖 100+ Supported LLM Models via LiteLLM

Switch between cloud APIs or 100% offline local models with a single command:

# Google Gemini Flash (High speed & rate limits)
m2 config set model gemini/gemini-flash-latest

# DeepSeek V4-Flash (Ultra-low token cost)
m2 config set model deepseek/deepseek-chat

# Anthropic Claude 3.5 Haiku (High precision reasoning)
m2 config set model claude-3-5-haiku-20241022

# Local Ollama (100% Offline, 0 API cost)
m2 config set model ollama/qwen2.5-coder:7b
m2 config set api_base http://localhost:11434

# Test your active connection
m2 config test

# Inspect active configuration
m2 config show

For full details, see the Multi-Provider Configuration Guide.

🛠️ CLI Command Reference

m1-m2-agent provides a complete command-line toolkit:

For full CLI options, see the Complete CLI Reference.

🏛️ Tri-Modal Architecture

                          ┌───────────────────────────────┐
                          │              L2               │
                          │   Frontier Reasoner (M1)      │
                          │   Plan • Decide • Review      │
                          └───────┬───────────────┬───────┘
                                  │               │
                          Path A  │        Path B │ (Direct Precision Fallback)
                      (Delegated) │               │
                                  ▼               │
                          ┌───────────────┐       │
                          │      L1       │       │
                          │  Worker (M2)  │       │
                          │ Context F/W   │       │
                          └───────┬───────┘       │
                                  │               │
                                  ▼               ▼
                          ┌───────────────────────────────┐
                          │              L0               │
                          │  Deterministic Fast Execution │
                          │   AST • Ripgrep • Git • LSP   │
                          └───────────────────────────────┘

• Path A (Delegated Worker): Heavy searches, AST outlines, multi-step refactorings, test runs.
• Path B (Direct Precision Fallback): Subtle race condition diagnosis, security audits, isolated single-file diffs.
• Path C (Autonomous TDD Investigation): Red-Green diagnostic loop isolating test failures with reproduction scripts and verified patches.

🐍 Python SDK Usage

from m1_m2_agent import M1OrchestratorAgent, TaskContract

# Initialize agent for current workspace
agent = M1OrchestratorAgent(workspace_root=".")

# Execute task with Context Firewall compression
response = agent.route_and_execute(
    objective="Locate all database connection pools and check for resource leaks",
    execution_path="PATH_A_DELEGATED"
)

print("Synthesized Result:\n", response["result"])
print("Structured Evidence:\n", response.get("evidence"))

# Inspect token savings & KPIs
telemetry = agent.get_telemetry_report()
print(f"Context Compression Ratio: {telemetry['context_compression_ratio']:.1f}%")
print(f"Frontier Token Avoidance:  {telemetry['frontier_token_avoidance_rate']:.1f}x")
print(f"Cost Reduction:            {telemetry['cost_reduction_pct']:.1f}%")

🌐 Live Webview HUD Dashboard

Launch the browser HUD on http://localhost:4040:

m2 hud

• Live Event Stream: Turn-by-turn thoughts, tool calls, and execution outputs via SSE.
• Real-Time Gauges: Live CCR, FTAR, and API cost reduction metrics.
• Zero-Token AST Explorer: Interactive visual map of all Python classes and methods.
• Git Inspector: Live diff hunks and file status tracking.
• Transcript Scrubber: Step-by-step history replay with automatic secret redaction.

📚 Documentation Index

• 2-Minute Quickstart
• Complete CLI Reference
• Multi-Provider LLM Guide
• The M1/M2 Architecture Philosophy
• Full System Architecture
• Real-World Setup Guide

📄 License

Apache License 2.0. See LICENSE for details.