A production-ready multi-agent system for autonomous software development with comprehensive monitoring, error handling, and configuration management.

• Mastra Agent Framework: Modern agent orchestration with built-in LLM call tracking
• Google Gemini Integration: Advanced AI models via LiteLLM for better performance
• Browser Automation: Stagehand integration for web-based tasks
• Fail-Fast Error Handling: Immediate quota protection with comprehensive reporting
• Budget Management: Real-time budget tracking and quota monitoring
• Circuit Breaker: Automatic API protection with configurable thresholds
• Configuration Management: Flexible configuration with validation and fallbacks

• Supervisor Agent: Manages Codex CLI worker instances with scalability (1-2 workers)
• Plan Management: Creates, stores, and executes structured plans with steps
• Task Coordination: Generates tasks for Codex CLI workers with proper context
• Memory System: Persistent storage using Mastra's SQLite database
• Configuration Integration: Unified configuration system with environment variable support

• Real-time Agent Monitoring: Live agent activity and performance tracking
• LLM Call Analytics: Detailed tracking of all AI model interactions
• Memory Management: Persistent agent memory with SQLite database
• Tool Integration: Visual tool usage and browser automation monitoring

• Project Management: Create, manage, and monitor projects
• Configuration: Validate, generate, and manage configurations
• Error Reporting: Comprehensive error analysis and recommendations
• System Health: Real-time system health monitoring
• Quota Management: Real-time quota and budget status monitoring
• Fail-Fast Control: Enable/disable fail-fast behavior for quota protection
• Migration: Automatic project migration and rollback
• Dashboard Integration: Access to real Mastra Playground for monitoring
• Memory Management: Memory system status, cleanup, and monitoring
• Unified Error Handling: Python-Mastra integrated error reporting

• Python 3.11+
• Node.js 18+ (for adapters)
• Git
• Google AI API key (for Gemini models)
• Browserbase account (for browser automation)

1. Clone the repository:

git clone <repository-url>
cd autonomous-lab

2. Set up the environment:

# Install Python dependencies
make install

# Install Node.js dependencies for adapters
cd adapters && npm install && cd ..

# (Optional) Create a .env for non-sensitive overrides
cp .env.example .env
# The credential vault replaces most secrets stored in .env

3. Configure your API keys:

# Initialise the encrypted credential vault (writes to logs/credentials/)
swarm vault init

# Store required secrets (hidden prompts will confirm values)
swarm vault set google_ai_api_key
swarm vault set browserbase_api_key
swarm vault set browserbase_project_id

# View stored entries (metadata only) and recent audit events
swarm vault list
swarm vault audit

# The system automatically loads vault secrets into the environment at runtime.
# You can still define fallback values in .env, but vault entries take precedence.

4. Start the system:

# Start the enhanced Python service
swarm run

# Open the Mastra Playground dashboard
swarm dashboard

# Or use the Makefile for convenience
make dashboard

1. Create a new project:

swarm create <project-name>

2. Monitor system health:

swarm system-health

3. Generate error report:

swarm error-report

4. Validate configuration:

swarm config-validate

5. Monitor quota and budget status:

swarm quota-status
swarm budget-status

6. Enable fail-fast mode for quota protection:

swarm fail-fast --enable

7. Run golden-path smoke + lint verification:

swarm smoke
# or skip lint to iterate faster
swarm smoke --lint false
# pass --skip-browser-check when Stagehand/Browserbase are not configured yet
swarm smoke --skip-browser-check

8. Reset queues before reruns:

swarm cleanup
# archives stale artifacts to logs/archives/queue-<timestamp>/

9. Access the Mastra Playground dashboard:

swarm dashboard

10. Check memory system status:

swarm memory-status

11. View unified error reports:

swarm unified-error-report

The system now integrates with the real Mastra Playground for comprehensive agent monitoring and management.

• Real-time Agent Monitoring: Live agent activity and performance tracking
• Tool Execution: Direct execution of Codex CLI, Browser, and FFmpeg tools
• Memory Management: Visual memory system monitoring and management
• Error Handling: Unified error reporting and system health monitoring
• LLM Analytics: Detailed tracking of all AI model interactions

# Basic dashboard access
swarm dashboard

# Auto-start the Playground
swarm dashboard --auto-start

# Open in browser automatically
swarm dashboard --open-browser

# Full experience (auto-start + open browser)
swarm dashboard --auto-start --open-browser

• Enhanced Python Service: HTTP API bridge at http://localhost:8000
• Memory System: Persistent SQLite database with agent-specific settings
• Error Handling: Unified Python-Mastra error reporting system
• Tool Integration: Seamless execution of Python tools via Mastra agents

# Basic dashboard
make dashboard

# Auto-start Playground
make dashboard-auto

# Open in browser
make dashboard-open

# Full experience
make dashboard-full

The system includes comprehensive fail-fast error handling to prevent quota exhaustion and provide immediate feedback on API issues.

• Immediate Quota Protection: System stops immediately when quota is exceeded
• Enhanced Quota Detection: Detects all quota-related error patterns
• Circuit Breaker: Automatic API protection with configurable thresholds
• Budget Integration: Real-time budget tracking and quota monitoring
• Loud Error Reporting: Prominent visual warnings for quota issues
• Graceful Shutdown: Automatic shutdown when budget thresholds are exceeded

Enable fail-fast behavior in swarm.yaml:

codex:
  fail_fast: true  # Enable fail-fast behavior
  quota_aware: true  # Enable quota-aware error handling
  aggressive_quota_detection: true  # Use enhanced quota detection

  # Circuit breaker configuration
  circuit_breaker_failure_threshold: 2
  circuit_breaker_recovery_timeout: 60
  circuit_breaker_quota_failure_threshold: 1
  circuit_breaker_quota_recovery_timeout: 300

# Check quota and budget status
swarm quota-status
swarm budget-status

# Enable/disable fail-fast mode
swarm fail-fast --enable
swarm fail-fast --disable
swarm fail-fast --show-status

# Monitor system health
swarm status  # Shows budget and circuit breaker status

1. Check quota status:

   swarm quota-status

2. Review budget spending:

   swarm budget-status

3. Enable fail-fast mode:

   swarm fail-fast --enable

4. Monitor system health:

   swarm status

The system uses a flexible configuration system with multiple validation levels:

• Strict: All options must be explicitly defined
• Moderate: Some options can use defaults
• Lenient: Minimal configuration required

Example configuration (swarm.yaml):

project:
  name: "my-project"
  description: "Project description"

agents:
  max_workers: 4
  timeout: 300

monitoring:
  enabled: true
  metrics_interval: 60

error_handling:
  fail_fast: true
  log_level: "INFO"

make test

make lint

make build

The system is built with a modern modular architecture:

• Mastra Core: Agent framework with built-in LLM call tracking and memory management
• Google Gemini: Advanced AI models via LiteLLM for better performance and cost efficiency
• Stagehand: Browser automation for web-based tasks and interactions
• SQLite: High-performance database for agent memory and task persistence
• CLI: Command-line interface for system management
• Web GUI: Mastra's built-in web interface for monitoring and management (Phase 3)

• Phase 1.1: Mastra Dependencies Added
• Phase 1.2: Mastra Core Structure Created
• Phase 1.3: Mastra Supervisor Agent Created
• Phase 1.4: Configuration System Integrated

• Phase 2.1: Creating Mastra Tools
• Phase 2.2: Migrating Task Queue System
• Phase 2.3: Integrating Fail-Fast Logic

• Phase 3.1: Remove FastAPI Dashboard
• Phase 3.2: Configure Mastra Web GUI
• Phase 3.3: Update CLI Commands

• Phase 4.1: Browser Automation Integration
• Phase 4.2: End-to-End Testing
• Phase 4.3: Documentation and Cleanup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

[License information]

For support and questions:

• Create an issue in the repository
• Check the documentation in the docs/ directory
• Review the implementation plan in IMPLEMENTATION_PLAN.md