A high-performance Rust CLI that enhances Claude Code with parallel AI development capabilities.
MAOS is a compiled Rust binary that replaces fragile Python hook scripts with a fast, reliable CLI. It enhances Claude Code's ability to work with multiple AI agents in parallel through automatic workspace isolation and intelligent coordination.
Key Features:
- 🚀 Blazing Fast: Target <10ms execution (currently ~50-200ms with Python bootstrap)
- 🔒 Rock Solid: Compiled binary that can't be accidentally broken
- 📦 Easy Install:
npx @maos/cliorbrew install maos(coming soon) - 👻 Invisible: Users interact with Claude Code normally
Bootstrap Phase: MAOS currently uses Python scripts to implement all features while we build the Rust CLI. This means you can use MAOS today! The Python implementation in
.claude/hooks/provides full functionality and will be replaced by themaosbinary with the same features but better performance.
⚡ See the Quick Start Guide to get running in 5 minutes!
MAOS is currently in bootstrap phase - the Python implementation in .claude/hooks/ provides full functionality while we build the Rust CLI.
Use MAOS Today:
- Clone this repository
- Configure your
.claude/settings.jsonwith Python hooks - Full orchestration features work now!
See CONTRIBUTING.md for setup instructions.
When the Rust CLI is released, installation will be simple:
# Via NPX (recommended)
npx @maos/cli setup
# Via Homebrew
brew install maos
# Direct download
curl -sSL https://raw.githubusercontent.com/clafollett/maos/main/scripts/install.sh | shThe Rust CLI will automatically update your settings.json hooks during installation!
When complete, update your Claude Code settings.json:
{
"hooks": {
"PreToolUse": [{
"command": "maos pre-tool-use" // Currently: uv run script.py
}],
"PostToolUse": [{
"command": "maos post-tool-use"
}]
}
}That's it! MAOS now handles all orchestration automatically.
- User talks to Claude Code: "Build me a complete authentication system"
- Claude Code decides to use multiple agents for parallel work
- MAOS hooks automatically:
- Create isolated git worktrees for each agent
- Prevent file conflicts between agents
- Track progress and coordinate work
- Clean up when complete
- Results are seamlessly integrated back
No new commands to learn. No complex setup. Just better parallel AI development.
User → Claude Code → settings.json → MAOS CLI
↓
┌────────┴────────┐
│ Rust Binary │
│ • Security │
│ • Orchestration │
│ • TTS & Notify │
└────────┬────────┘
↓
┌─────────────┴─────────────┐
│ Git Worktrees │
│ • backend-engineer/ │
│ • frontend-engineer/ │
│ • qa-engineer/ │
└───────────────────────────┘
# Core hooks
maos pre-tool-use # Security checks + orchestration
maos post-tool-use # Cleanup + logging
# Notifications
maos notify # Smart TTS notifications
maos stop # Session end with TTS
maos subagent-stop # Sub-agent cleanup
# Monitoring
maos prompt-submit # Log user prompts
maos session-info # Current session status
maos worktree-list # Active worktrees- Blocks dangerous
rm -rfcommands before execution - Prevents access to
.envfiles containing secrets - Validates all paths to prevent directory traversal
- Compiled binary ensures tamper-proof operation
- Written in Rust for maximum speed
- Zero Python interpreter overhead (when complete)
- Sub-10ms hook execution (vs current ~50-200ms)
- Handles hundreds of tool calls efficiently
- Multi-provider TTS support (ElevenLabs, OpenAI, macOS, pyttsx3)
- Automatic provider selection based on API keys
- Configurable voices and text limits
- Session completion announcements
- NPX for Node.js users:
npx @maos/cli - Homebrew for macOS:
brew install maos - Direct binaries for all platforms
- No Rust toolchain needed for users
- Rust stable toolchain
- Git 2.5+ (for worktree support)
- Just task runner
# Clone the repository
git clone https://github.com/clafollett/maos.git
cd maos
# Install Rust (if needed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build the project
cargo build --release
# Run tests
cargo test
# Install locally for testing
cargo install --path .- Automatic Isolation: Each agent works in its own git worktree
- Conflict Prevention: File locking prevents simultaneous edits
- Session Management: Tracks multi-agent workflows seamlessly
- Progress Tracking: Real-time visibility into agent activities
- Rust CLI: Fast, reliable, single binary distribution
- File-Based Coordination: JSON files for state management
- Hook Integration: Works through Claude Code's settings.json
- Git Worktrees: Complete workspace isolation per agent
- Quick Start Guide - Get running in 5 minutes! ⚡
- Installation - All installation methods
- Architecture - Technical design
- Development Workflow - Contribution standards
- Quick Start Guide: Get running in 5 minutes! ⚡
- Installation Guide: NPX, Homebrew, and binary installation
- CLI Reference: Complete command documentation
- Configuration: settings.json and config options
- Migration Guide: Moving from Python hooks to MAOS CLI
- Troubleshooting: Common issues and solutions 🛠️
- Architecture Overview: Rust crate structure and design
- Contributing Guide: Development setup and guidelines
- Development Workflow: Standards and processes
- Core CLI structure with clap
- Security features (rm -rf blocking, .env protection)
- MAOS orchestration (worktrees, sessions, locks)
- TTS integration (multi-provider support)
- Configuration management
- Comprehensive test suite
- NPM package for npx distribution
- Homebrew formula
- GitHub releases with binaries
- Installation scripts
- Auto-update mechanism
- Performance profiling and optimization
- Advanced debugging commands
- Plugin system for custom hooks
- Web dashboard for monitoring
- Integration with more Claude Code features
- Eliminate Python startup overhead on every tool call
- Handle hundreds of operations without slowdown
- Near-instant execution for all commands
- Compiled binary that can't be accidentally modified
- Consistent behavior across all environments
- Enterprise-ready security and reliability
- Simple installation via familiar tools (NPX, Homebrew)
- Clean configuration in settings.json
- Comprehensive documentation and support
- Written in Rust for long-term maintainability
- Extensible architecture for new features
- Active development and community
maos/
├── Cargo.toml # Workspace configuration
├── crates/
│ ├── maos-cli/ # Main CLI application
│ │ ├── Cargo.toml
│ │ └── src/
│ │ ├── main.rs # CLI entry point
│ │ └── commands/ # Subcommand implementations
│ ├── maos-core/ # Core orchestration logic
│ │ ├── Cargo.toml
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── session.rs # Session management
│ │ └── worktree.rs # Git worktree operations
│ ├── maos-security/ # Security features
│ │ ├── Cargo.toml
│ │ └── src/
│ │ ├── lib.rs
│ │ └── validators.rs # Path and command validation
│ └── maos-tts/ # TTS provider integration
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ └── providers/ # ElevenLabs, OpenAI, etc.
├── .claude/
│ ├── agents/ # Agent configurations
│ └── config.example.json # Example configuration
├── docs/
│ ├── cli/ # User documentation
│ └── development/ # Contributor guides
└── scripts/
├── install.sh # Installation script
└── release.sh # Release automation
We welcome contributions! See CONTRIBUTING.md for details.
- Performance First - Every millisecond counts in hook execution
- Type Safety - Leverage Rust's type system for reliability
- User Experience - Installation and usage must be effortless
- Backward Compatible - Smooth migration from Python hooks
- Well Tested - Comprehensive test coverage required
- Documentation: GitHub Wiki
- Issues: GitHub Issues
- Discussions: GitHub Discussions
MIT License - see LICENSE for details.
MAOS: Professional multi-agent orchestration for Claude Code. Fast. Reliable. Invisible.