maos-cli 0.3.0

Orchestrate swarms of Claude subagents with natural language

MAOS - Multi-Agent Orchestration System

Create and orchestrate Claude subagent swarms with simple natural language commands

What MAOS Does

MAOS lets you spawn multiple Claude agents that work in parallel on your tasks. Instead of writing Python code, just type what you want in plain English:

• "spawn 3 agents to review my code" → Creates 3 specialized Claude agents
• "implement the requirements in prd.md" → Distributes work across multiple agents
• "fix all the security issues" → Agents work together to find and fix problems

Installation (2 minutes)

Step 1: Install MAOS

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

# Or with pip
pip install maos-cli

Step 2: Start Using

# Go to any project directory
cd your-project

# Start MAOS chat interface
maos chat

That's it! Now type commands in natural language.

Quick Start Examples

Basic Usage (No Claude CLI Required)

When you run maos chat, MAOS creates Claude subagent files that define specialized agents:

MAOS> spawn 3 agents to review my code
✓ Created Claude subagents: reviewer, security-auditor, tester
✓ Agent files created in .claude/agents/

MAOS> show status
📊 3 agents ready for use
  • reviewer.md - Code review specialist
  • security-auditor.md - Security vulnerability scanner  
  • tester.md - Test coverage analyzer

The agents are created as Markdown files in .claude/agents/ directory. These work with Claude Code when it's installed.

With Claude CLI Installed (Full Functionality)

If you have Claude Code CLI installed, MAOS can actually run the agents:

# First, install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Authenticate with your API key
export ANTHROPIC_API_KEY="your-api-key"
# Or use: claude login

Now MAOS will spawn actual Claude processes:

MAOS> spawn 5 agents to analyze my codebase
✓ Created Claude subagents: architect, developer, tester, reviewer, security-auditor
✓ Spawned 5 Claude CLI instances
✓ Agents working in parallel...

MAOS> implement the PRD in requirements.md
✓ Analyzing requirements...
✓ Distributed 12 tasks across agents
⚡ Agents working:
  • architect: Designing system structure...
  • developer: Implementing core features...
  • tester: Writing test specifications...

What Gets Created

MAOS creates specialized Claude agents as Markdown files:

your-project/
├── .claude/
│   └── agents/
│       ├── reviewer.md        # Code review specialist
│       ├── developer.md       # Implementation expert
│       ├── tester.md          # Testing specialist
│       └── security-auditor.md # Security scanner
├── your_code.py
└── requirements.md

Each agent file looks like this:

---
name: reviewer
description: Code review specialist for quality and security
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer ensuring high standards...
[detailed instructions for the agent]

Natural Language Commands

Just type what you want:

Creating Agents

• spawn 3 agents to review my code
• create a swarm to implement the PRD
• start 5 agents for testing

Task Management

• implement requirements.md
• fix all security issues
• review the codebase
• write tests for everything

Monitoring

• show status
• list agents
• show progress

Utility

• help - Show commands
• exit - Leave MAOS

Installation Troubleshooting

If pipx is not installed:

python3 -m pip install --user pipx
pipx ensurepath
# Restart terminal, then:
pipx install maos-cli

If maos command not found:

# Add pipx binaries to PATH
export PATH="$HOME/.local/bin:$PATH"
# Add to your ~/.bashrc or ~/.zshrc to make permanent

For development/testing:

# Clone and install from source
git clone https://github.com/yourusername/maos.git
cd maos
pip install -e .

How It Works

1. You type a command in natural language
2. MAOS creates specialized agents as .claude/agents/*.md files
3. Each agent has expertise (reviewer, tester, developer, etc.)
4. With Claude CLI installed, MAOS spawns actual Claude processes
5. Agents work in parallel on your tasks

Requirements

• Python 3.11+ - For running MAOS
• Claude Code CLI (optional) - For actually running agents

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

Common Issues & Solutions

"Claude CLI not found"

This is normal! MAOS still creates agent files that you can use manually. To enable full functionality:

npm install -g @anthropic-ai/claude-code
claude login  # or export ANTHROPIC_API_KEY="..."

"No agents were created"

Check if the .claude/agents/ directory exists:

ls -la .claude/agents/

Clean up agents

rm -rf .claude/agents/*.md

License

MIT - Use freely in your projects!

Quick Links

• PyPI Package
• Report Issues
• Documentation