maos-cli 0.6.1

Orchestrate swarms of Claude subagents with natural language

MAOS - Multi-Agent Orchestration System v0.6.1

CORRECTLY orchestrates Claude Code subagents using the official subagent architecture!

🔥 CRITICAL FIX in v0.6.1

• v0.6.0 had wrong imports - was still using old process spawning
• v0.6.1 ACTUALLY creates subagent files in .claude/agents/
• Now properly uses the v3 components with subagent creation

🚨 BREAKING CHANGE in v0.6.x

MAOS now works with Claude Code's actual subagent system:

• ✅ Creates subagent definition files in .claude/agents/
• ✅ Uses Task tool delegation instead of spawning CLI processes
• ✅ Claude Code handles execution internally
• ✅ True parallel execution through Claude's native system
• ✅ No more subprocess errors - works as intended!

How It Actually Works Now

1. You describe your task → "Analyze this codebase and write tests"
2. MAOS creates subagent files → .claude/agents/analyzer.md, .claude/agents/tester.md
3. MAOS provides delegation prompts → "Use the analyzer subagent to..."
4. You execute with Task tool → Claude Code runs subagents in parallel
5. Results tracked in database → Full persistence and memory

🚀 What's New in v0.6.0

Complete Architecture Rewrite:

• ✅ Proper Subagent Creation - Creates .claude/agents/*.md files with YAML frontmatter
• ✅ Task Tool Integration - Generates delegation prompts for Claude Code
• ✅ No Process Spawning - Uses Claude's native subagent system
• ✅ Parallel Execution Works - Claude Code handles parallel tasks internally
• ✅ Database Tracking - Still tracks everything in SQLite
• ✅ Clean Architecture - Aligns with official Claude Code documentation

📦 Previous v0.4.0

Enhanced Task Understanding & Visibility:

• ✅ Smart Task Decomposition - Correctly parses explicit agent requests like "use 2 agents, one which understand requirements"
• ✅ Explainable AI - Shows task understanding and explains decomposition decisions
• ✅ Real-time Monitoring - Live progress updates for each agent during batch execution
• ✅ Better Timeout Handling - Detects stuck agents and provides clear timeout messages
• ✅ Enhanced Database Logging - All tasks and operations properly saved to database
• ✅ Improved Error Messages - Clear visibility into what each agent is doing

📦 Previous v0.3.2

Bug Fix Release:

• ✅ Fixed foreign key constraint issue in message bus
• ✅ Agents now properly created in database before messaging
• ✅ Prevents duplicate agent creation in database

📦 What's New in v0.3.1

Bug Fix Release:

• ✅ Fixed SQLite Row conversion issue for Python 3.13 compatibility
• ✅ Proper dictionary conversion from aiosqlite Row objects
• ✅ All database queries now return proper dictionaries

📦 What's New in v0.3.0

Complete Orchestration System:

• ✅ SQLite Persistence - All data stored in a robust database
• ✅ Task Decomposition - Automatically breaks tasks into parallel subtasks
• ✅ Session Management - Resume conversations, save/restore checkpoints
• ✅ Inter-Agent Communication - Agents coordinate and share information
• ✅ Smart Agent Allocation - Reuses existing agents when possible
• ✅ Real SDK Mode - Spawns Claude with -p for actual task execution

What MAOS Does

MAOS orchestrates multiple Claude CLI instances to work on complex tasks in parallel:

User: "Implement the requirements in prd.md"

MAOS:
├─ Analyzes requirements
├─ Decomposes into subtasks
├─ Allocates agents (creates new or reuses existing)
├─ Executes tasks in parallel batches
└─ Coordinates inter-agent communication

Installation

# Install with pipx (recommended)
pipx install maos-cli

# Or with pip
pip install maos-cli

Quick Start

1. Basic Chat Interface

# Start the orchestrator
maos chat

# Now use natural language
MAOS> Build a REST API with authentication

2. How It Works

When you give MAOS a task, it:

1. Decomposes - Breaks your request into parallel subtasks
2. Proposes Agents - Shows which agents it will create/reuse
3. Gets Approval - You approve the execution plan
4. Executes - Spawns Claude processes in SDK mode
5. Coordinates - Manages inter-agent communication
6. Reports - Shows progress and results

3. Example Session

MAOS> Implement the requirements in prd.md

Analyzing request and creating task plan...
Determining agent allocation...

═══════════════════════════════════════════════════
              Agent Allocation
───────────────────────────────────────────────────
Agent allocation proposal:
  • Creating 3 new agents
  • Reusing 2 existing agents

  NEW: architect-a3f2b1c8 (architect)
    → Design system architecture based on PRD
  NEW: developer-b4d5c2e9 (developer)  
    → Implement backend services according to PRD
  NEW: tester-c6e7d3fa (tester)
    → Write comprehensive tests for PRD features
  REUSE: security-auditor [session: 4d5e6f7a]
    → Review for security vulnerabilities
  REUSE: reviewer [session: 8b9c0d1e]
    → Review code quality and standards
═══════════════════════════════════════════════════

Estimated duration: 10.0 minutes
Estimated cost: $0.1500

Proceed with this plan? (y/n): y

Starting execution...
Spawning agents...
  ✓ Spawned architect-a3f2b1c8
  ✓ Spawned developer-b4d5c2e9
  ✓ Spawned tester-c6e7d3fa
  ↻ Resumed security-auditor
  ↻ Resumed reviewer

Executing batch 1/3
[Working... Agents collaborating]

💡 architect-a3f2b1c8 discovered: Database schema requires indexing
⚠️ developer-b4d5c2e9 needs from architect-a3f2b1c8: API endpoint specs

Execution complete!

Features

🧠 Intelligent Task Decomposition

• Automatically breaks complex tasks into subtasks
• Identifies dependencies between tasks
• Groups tasks for parallel execution

🤖 Smart Agent Management

• Creates specialized agents for different task types
• Reuses existing agents when appropriate
• Manages Claude sessions with SDK mode (claude -p)

💬 Inter-Agent Communication

• Agents can send messages to each other
• Broadcast discoveries to all agents
• Request dependencies from other agents

💾 Persistence & Checkpoints

• SQLite database stores all orchestration data
• Save/restore checkpoints for long-running tasks
• Resume sessions across multiple days

📊 Real-Time Monitoring

• Track agent progress
• View inter-agent messages
• Monitor resource usage

Commands

Natural Language

Just type what you want:

• "Build a REST API with authentication"
• "Review and optimize my codebase"
• "Fix all the failing tests"
• "Implement the requirements in prd.md"

System Commands

• status - Show current execution status
• save checkpoint <name> - Save current state
• restore <name> - Restore from checkpoint
• list checkpoints - Show available checkpoints
• pause - Pause execution
• resume - Resume execution
• help - Show available commands
• exit - Stop all agents and exit

Architecture

┌─────────────────────────────────────────────┐
│            Natural Language Input            │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│           Orchestrator Brain                 │
│  • Task Decomposer                          │
│  • Agent Allocator                          │
│  • Execution Planner                        │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│           Session Manager                    │
│  • Spawn Claude with -p <task>              │
│  • Resume sessions with --resume            │
│  • Manage process lifecycle                 │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│         Agent Message Bus                    │
│  • Inter-agent communication                │
│  • Message routing                          │
│  • Discovery broadcasting                   │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│         SQLite Persistence                   │
│  • Agents, Sessions, Tasks                  │
│  • Messages, Checkpoints                    │
│  • Complete relational storage              │
└─────────────────────────────────────────────┘

Requirements

• Python 3.11+
• Claude CLI (optional, for actual execution)

  npm install -g @anthropic-ai/claude-code
  export ANTHROPIC_API_KEY="your-api-key"
  

Advanced Usage

Auto-Approve Mode

Skip manual approval for agent proposals:

maos chat --auto-approve

Custom Database Location

maos chat --db-path /path/to/my/maos.db

Configuration File

Create .maos/config.yaml:

orchestrator:
  max_agents: 20
  auto_approve: false
  
persistence:
  db_path: ./maos.db
  
session:
  max_turns: 10
  timeout: 600

Troubleshooting

Claude CLI Not Found

MAOS works without Claude CLI - it creates agent definition files. To actually run agents, install Claude:

npm install -g @anthropic-ai/claude-code

Database Errors

Delete the database to start fresh:

rm maos.db

Session Issues

List and manage sessions:

MAOS> status
MAOS> list checkpoints
MAOS> restore <checkpoint-name>

Examples

Code Review

MAOS> Review all Python files for security issues and performance problems

[Creates security-auditor and performance-optimizer agents]
[Runs them in parallel across your codebase]
[Reports findings with specific file locations]

Test Generation

MAOS> Generate comprehensive tests for all modules

[Creates multiple tester agents]
[Each handles different modules in parallel]
[Produces test files with high coverage]

Documentation

MAOS> Document all public APIs and create a user guide

[Creates documentation-writer agents]
[Analyzes code and generates docs]
[Produces markdown documentation]

Version History

• v0.3.2 - Fixed foreign key constraint issue in message bus
• v0.3.1 - Fixed SQLite Row conversion for Python 3.13 compatibility
• v0.3.0 - Complete orchestration with SQLite, parallel execution, checkpoints
• v0.2.6 - Fixed agent spawning, improved natural language
• v0.2.0 - Added Claude CLI integration
• v0.1.0 - Initial release with agent definitions

Contributing

PRs welcome! Check out our contribution guidelines.

License

MIT - See LICENSE file

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Docs

---

Built with ❤️ for the AI orchestration community