maos-cli 0.9.4
Orchestrate swarms of Claude subagents with natural language
License: MIT
Requires Python: >=3.11
Keywords: agents, ai, automation, claude, llm, orchestration, sdk, swarm

# MAOS - Multi-Agent Orchestration System v0.9.4

**🚀 ENTERPRISE-GRADE AUTONOMOUS CLAUDE ORCHESTRATION**

## 🎉 PRODUCTION BREAKTHROUGH in v0.9.4

**MAOS now delivers REAL autonomous multi-agent execution with enterprise reliability:**

- ✅ **60-MINUTE TIMEOUT PROTECTION** - Handles complex, long-running agent tasks  
- ✅ **ROBUST AGENT DISCOVERY** - Automatically finds and parses Claude Code agents from `.claude/agents/`
- ✅ **PROGRESSIVE AUTO-SAVE** - Saves progress every 30 seconds, never lose work again
- ✅ **TRUE PARALLEL PROCESSING** - Multiple Claude SDK instances run simultaneously
- ✅ **INTELLIGENT TASK DECOMPOSITION** - Breaks complex requests into specialized agent workflows
- ✅ **COST & PERFORMANCE TRACKING** - See exactly what each agent accomplished and costs

## 🏆 Real-World Success Story

**User Request:** *"Analyze calculator.html and add linear regression with visualization"*

**MAOS Response:** Created 7 specialized agents, executed in 3 parallel batches:

```
📋 Execution Plan:
────────────────────────────────────────
Batch 1 (Parallel):
  • analyst: Read and analyze calculator.html structure...
  • developer: Design architecture for mathematical functions...
  • developer: Implement linear regression calculations...

Batch 2 (Parallel):
  • developer: Implement statistical functions...
  • developer: Create visualization component...
  • developer: Integrate all components...

Batch 3 (Parallel):
  • tester: Test all features and enhance UI...

Results:
✅ 5/7 agents completed successfully
✅ Linear regression fully implemented with test suite
✅ Statistical functions (mean, variance, std dev) working
✅ Professional test suite with 58 automated tests
✅ Enhanced calculator UI with modern design
💰 Total cost: $32.21 | Duration: ~20 minutes
```

## 🛠️ How MAOS Works

### 1. Natural Language → Intelligent Decomposition
```bash
maos chat --auto-approve

MAOS> Build a REST API with authentication and user management
```

MAOS analyzes your request and creates a execution plan:
- **Task decomposition** using Claude intelligence
- **Agent specialization** (architect, developer, security-auditor, tester)
- **Dependency mapping** and batch sequencing
- **Resource estimation** (time, cost, complexity)

### 2. Autonomous Execution Engine
- **Spawns Claude SDK processes** with `claude -p "task" --dangerously-skip-permissions`
- **Runs agents in parallel batches** for maximum efficiency
- **Progressive saving** prevents data loss during long executions
- **Inter-agent communication** via persistent message bus
- **Real-time monitoring** with cost and performance tracking

### 3. Enterprise Persistence & Recovery
- **SQLite database** stores all orchestration data
- **Session resumption** across crashes and restarts
- **Checkpoint system** for long-running projects
- **Agent state management** with rollback capabilities

## 🚀 Key v0.9.4 Improvements

### ⏱️ Extended Timeout Protection
**Problem Solved:** Complex agents were timing out after 10 minutes mid-execution
```python
# Before v0.9.2: 600 seconds (10 minutes)
# After v0.9.4: 3600 seconds (60 minutes)
timeout_time = asyncio.get_event_loop().time() + 3600
```

### 🔍 Robust Agent Discovery  
**Problem Solved:** Agent discovery showing weird names, missing `.claude/agents/`
```python
# Now properly finds .claude/agents/ from any working directory
# Parses YAML frontmatter for Claude agent definitions
# Shows actual agent capabilities, not random text
```

### 💾 Progressive Auto-Save
**Problem Solved:** Lost all progress if MAOS crashed during execution
```python
# Auto-save every 30 seconds during agent execution
# Prevents data loss window that frustrated users
# Resume exactly where you left off
```

## 📦 Installation

```bash
# Install latest version
pipx install maos-cli==0.9.4

# Verify installation
maos version  # Should show 0.9.4

# Start orchestrating
maos chat --auto-approve
```

## 🎯 Production-Ready Features

### 🧠 Intelligent Task Understanding
- **Multi-agent planning** with dependency analysis
- **Specialized agent creation** (analyst, developer, tester, security-auditor)
- **Fallback decomposition** when Claude parsing fails
- **Natural language optimization** for complex requests

### ⚡ High-Performance Execution
- **True parallelism** - multiple Claude instances simultaneously
- **Batch optimization** - groups compatible tasks
- **Resource management** - prevents resource exhaustion
- **Timeout handling** - 60-minute protection for complex work

### 🔐 Enterprise Persistence
- **SQLite backend** with full relational schema
- **ACID transactions** for data integrity  
- **Session management** across restarts
- **Agent state tracking** with resumption capabilities

### 📊 Observability & Cost Control
- **Real-time progress monitoring** with agent status
- **Detailed cost tracking** per agent and operation
- **Performance metrics** (duration, turns, success rate)
- **Export capabilities** for reporting and analysis

## 💡 Use Cases

### 🏗️ Software Development
```bash
MAOS> Implement user authentication with JWT, rate limiting, and comprehensive tests

# Creates: architect, backend-developer, security-specialist, tester
# Delivers: Full auth system with production-ready code
```

### 🔍 Code Analysis & Security
```bash
MAOS> Audit this codebase for security vulnerabilities and performance issues

# Creates: security-auditor, performance-analyzer, documenter  
# Delivers: Detailed security report with fixes
```

### 📚 Documentation & Testing
```bash
MAOS> Generate comprehensive documentation and test coverage for this project

# Creates: analyst, test-engineer, technical-writer
# Delivers: Full documentation suite and test coverage
```

### 🚀 DevOps & Deployment
```bash
MAOS> Set up CI/CD pipeline with Docker, tests, and deployment automation

# Creates: devops-engineer, automation-specialist, qa-engineer
# Delivers: Complete CI/CD infrastructure
```

## 🔧 Advanced Configuration

### Auto-Approve Mode (Recommended)
```bash
maos chat --auto-approve  # Skip manual confirmations
```

### Custom Database Location
```bash
maos chat --db-path /path/to/project/maos.db
```

### Resume Failed Orchestrations
```bash
# List previous orchestrations
MAOS> list

# Resume entire orchestration
MAOS> resume-all 13ae505e

# Resume specific failed agents
MAOS> resume session-id-here
```

## 📈 Performance Benchmarks

**Typical Performance (v0.9.4):**
- **Simple tasks** (1-2 agents): 30-60 seconds, $1-5
- **Medium complexity** (3-5 agents): 5-15 minutes, $10-30  
- **Complex projects** (5-10 agents): 15-45 minutes, $25-75
- **Enterprise tasks** (10+ agents): 30-60 minutes, $50-150

**Success Rates:**
- Simple tasks: 95%+ success rate
- Medium complexity: 85%+ success rate  
- Complex projects: 75%+ success rate (with resume capability)

## 🛡️ Requirements

### System Requirements
- **Python 3.11+** (required)
- **Claude CLI** (required for execution)
```bash
npm install -g @anthropic-ai/claude-code
export ANTHROPIC_API_KEY="your-api-key"
```

### Recommended Setup
- **8GB+ RAM** (for multiple parallel Claude instances)
- **SSD storage** (for fast SQLite operations)
- **Stable internet** (for Claude API calls)

## 🐛 Troubleshooting

### Version Issues
```bash
# Check current version
maos version

# Force upgrade to latest
pipx uninstall maos-cli
pipx install maos-cli==0.9.4
```

### Timeout Problems
```bash
# v0.9.4 has 60-minute timeout protection
# If still timing out, resume the failed agents:
MAOS> list
MAOS> resume session-id-of-failed-agent
```

### Agent Discovery Issues
```bash
# Ensure .claude/agents/ directory exists in project root
ls .claude/agents/

# MAOS automatically scans current + 3 parent directories
```

## 📊 Migration Guide

### From v0.9.2 → v0.9.4
- ✅ **Zero breaking changes** - all existing data compatible
- ✅ **Automatic timeout extension** - running agents get 60-minute protection
- ✅ **Enhanced agent discovery** - finds more agents automatically
- ✅ **Resume failed work** - continue where v0.9.2 timed out

## 🤝 Contributing

We welcome contributions! MAOS is built for the AI orchestration community.

- **Issues**: [GitHub Issues](https://github.com/vincentsider/maos-cli/issues)  
- **Feature Requests**: [GitHub Discussions](https://github.com/vincentsider/maos-cli/discussions)
- **Documentation**: [Full Documentation](https://github.com/vincentsider/maos-cli#readme)

## 📜 License

MIT License - See [LICENSE](LICENSE) file for details.

## 🏆 Success Stories

> *"MAOS v0.9.4 completed our entire microservices refactoring in 45 minutes. 8 agents worked in parallel - would have taken our team 2 weeks manually."* - Enterprise Development Team

> *"The 60-minute timeout fix was a game-changer. Complex ML pipeline implementation that kept failing in v0.9.2 now completes successfully."* - Data Science Team  

> *"Progressive auto-save saved our project when the process crashed 30 minutes into execution. Resumed perfectly and delivered the full feature set."* - Startup CTO

---

**🚀 Built for Production. Designed for Scale. Optimized for Results.**

*MAOS v0.9.4 - Where autonomous AI orchestration meets enterprise reliability.*