Metadata-Version: 2.4
Name: maos-cli
Version: 0.9.3
Summary: Orchestrate swarms of Claude subagents with natural language
Project-URL: Homepage, https://github.com/vincentsider/maos-cli
Project-URL: Documentation, https://github.com/vincentsider/maos-cli#readme
Project-URL: Repository, https://github.com/vincentsider/maos-cli
Project-URL: Issues, https://github.com/vincentsider/maos-cli/issues
Project-URL: Source Code, https://github.com/vincentsider/maos-cli
Author-email: Vincent Sider <vincent@maos.dev>
Maintainer-email: Vincent Sider <vincent@maos.dev>
License: MIT
License-File: LICENSE
Keywords: agents,ai,automation,claude,llm,orchestration,sdk,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.9.0
Provides-Extra: api
Requires-Dist: fastapi>=0.104.1; extra == 'api'
Requires-Dist: httpx>=0.25.2; extra == 'api'
Requires-Dist: pydantic>=2.5.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.24.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: black>=23.11.0; extra == 'dev'
Requires-Dist: mypy>=1.7.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.3; extra == 'dev'
Requires-Dist: ruff>=0.1.6; extra == 'dev'
Provides-Extra: full
Requires-Dist: aioredis>=2.0.1; extra == 'full'
Requires-Dist: cryptography>=41.0.7; extra == 'full'
Requires-Dist: fastapi>=0.104.1; extra == 'full'
Requires-Dist: httpx>=0.25.2; extra == 'full'
Requires-Dist: prometheus-client>=0.19.0; extra == 'full'
Requires-Dist: pydantic>=2.5.0; extra == 'full'
Requires-Dist: pyjwt>=2.8.0; extra == 'full'
Requires-Dist: redis>=5.0.1; extra == 'full'
Requires-Dist: sqlalchemy[asyncio]>=2.0.23; extra == 'full'
Requires-Dist: uvicorn[standard]>=0.24.0; extra == 'full'
Provides-Extra: redis
Requires-Dist: aioredis>=2.0.1; extra == 'redis'
Requires-Dist: redis>=5.0.1; extra == 'redis'
Description-Content-Type: text/markdown

# MAOS - Multi-Agent Orchestration System v0.7.0

**🚀 AUTONOMOUS MULTI-AGENT EXECUTION IS HERE!**

## 🎉 MAJOR BREAKTHROUGH in v0.7.0

**MAOS now runs Claude agents AUTONOMOUSLY in PARALLEL:**
- ✅ **REAL autonomous execution** using Claude SDK with `--dangerously-skip-permissions`
- ✅ **TRUE parallel processing** - multiple Claude instances run simultaneously
- ✅ **NO manual intervention** - fully automated orchestration
- ✅ **Session persistence** - resume conversations with `--resume`
- ✅ **Cost tracking** - see exactly how much each agent costs
- ✅ **Performance monitoring** - track execution times and turns

## How It Actually Works Now

1. **You describe your task** → "Analyze this codebase and write tests"
2. **MAOS decomposes into subtasks** → Creates batches for parallel execution
3. **MAOS spawns Claude SDK processes** → Each agent runs `claude -p "task" --dangerously-skip-permissions`
4. **Agents run AUTONOMOUSLY** → No manual intervention, no prompts, just execution
5. **Results returned in real-time** → See progress, costs, and outputs as they complete

## 🚀 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

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

# Or with pip
pip install maos-cli
```

## Quick Start

### 1. Basic Chat Interface

```bash
# 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)
  ```bash
  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:

```bash
maos chat --auto-approve
```

### Custom Database Location

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

### Configuration File

Create `.maos/config.yaml`:

```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:
```bash
npm install -g @anthropic-ai/claude-code
```

### Database Errors
Delete the database to start fresh:
```bash
rm maos.db
```

### Session Issues
List and manage sessions:
```bash
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](CONTRIBUTING.md).

## License

MIT - See [LICENSE](LICENSE) file

## Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/maos/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/maos/discussions)
- **Documentation**: [Full Docs](https://maos.dev/docs)

---

**Built with ❤️ for the AI orchestration community**