β οΈ NOT UNDER ACTIVE DEVELOPMENTThis project is no longer being actively maintained. CI/CD pipelines have been disabled. The code remains available for reference and archival purposes.
Last active: January 2026
Hierarchical AI agent system that mimics organizational structures for autonomous task management
RecursiveManager is a revolutionary AI agent orchestration system that models organizational hierarchies. Just as a CEO delegates to managers who delegate to workers, RecursiveManager enables AI agents to hire subordinates, manage tasks, escalate issues, and coordinate work across a recursive tree of specialized agents.
- Recursive Agent Hierarchies: Agents can hire and manage subordinates, creating organizational depth
- Dual Instance Types: Continuous execution for active work + reactive triggers for messages/events
- File-Based Persistence: Each agent has its own workspace with notes, tasks, and context
- Multi-Framework Support: Works with Claude Code, OpenCode, and other AI coding frameworks
- Smart Scheduling: Time-based triggers, continuous execution, and reactive messaging
- Multi-Platform Integration: Slack, Telegram, email, and internal messaging
- Quality-First: Multi-perspective analysis before all major decisions
Quality over cost. RecursiveManager prioritizes correctness and thorough analysis over speed. Every major decision is analyzed from multiple perspectives (security, architecture, UX, etc.) to ensure robust outcomes.
Stateless execution. Every agent execution starts with a fresh memory context, reading all state from files. This prevents context window decay and enables truly long-running projects.
Business-like structure. Agents behave like employees in a company: they have roles, goals, managers, and subordinates. They hire, fire, escalate, and coordinate just like real organizations.
Install RecursiveManager with a single command:
curl -fsSL https://raw.githubusercontent.com/aaron777collins/RecursiveManager/master/scripts/install-binary.sh | bashThis downloads pre-built binaries, verifies checksums, and adds RecursiveManager to your PATH.
π Full Installation Guide - Detailed instructions for all platforms
Manual Binary Install:
- Download from Releases
- Extract:
tar xzf recursivemanager-v1.0.0-*.tar.gz -C ~/.recursivemanager - Add to PATH:
export PATH="$HOME/.recursivemanager:$PATH"
From Source:
git clone https://github.com/aaron777collins/RecursiveManager.git
cd RecursiveManager
npm install && npm run build && npm linkCI/CD (Headless):
VERSION=1.0.0 INSTALL_DIR=/opt/rm curl -fsSL https://raw.githubusercontent.com/aaron777collins/RecursiveManager/master/scripts/install-binary.sh | bash# Initialize with a high-level goal
recursivemanager init "Build a SaaS product for task management"
# The CEO agent will:
# 1. Analyze the goal from multiple perspectives
# 2. Create a strategic plan
# 3. Hire necessary team members (CTO, CMO, CFO, etc.)
# 4. Each hired agent further delegates as needed
# Monitor progress
recursivemanager status
# Output:
# ββ Organization Chart ββββββββββββββββββββββββββ
# β CEO β
# β ββ CTO (Build the application) β
# β β ββ Backend Dev (API development) β
# β β ββ Frontend Dev (UI development) β
# β ββ CMO (Market the product) β
# β ββ CFO (Manage finances) β
# ββββββββββββββββββββββββββββββββββββββββββββββββUpgrade to the latest version:
recursivemanager-upgradeOr upgrade to a specific version:
recursivemanager-upgrade 2.0.0π Full Upgrade Guide - Upgrade, downgrade, rollback, and version management
- Installation Guide - Complete installation instructions
- Upgrade Guide - Version management and upgrades
- API Documentation - Complete API reference
- Architecture - System design and internals
- Contributing - How to contribute
RecursiveManager includes a self-update mechanism:
# Check for updates
recursivemanager update --check
# Update to latest version
recursivemanager update
# Update to specific version
recursivemanager update 0.2.0
# Rollback to previous version
recursivemanager rollback
# View version history
recursivemanager update --historyπ Full Documentation - Visit our comprehensive documentation website
- Installation Guide - Detailed installation instructions
- Quick Start - Get started quickly
- Configuration - Configuration options
- CLI Reference - Command-line interface documentation
- API Reference - API documentation
- Architecture - System architecture
- COMPREHENSIVE_PLAN.md - Complete system architecture and design
- MULTI_PERSPECTIVE_ANALYSIS.md - Analysis from 8 expert perspectives
- FILE_STRUCTURE_SPEC.md - Detailed file structure and schemas
- EDGE_CASES_AND_CONTINGENCIES.md - Edge case handling
- IMPLEMENTATION_PHASES.md - Phased implementation plan
- AI_PROVIDER_GUIDE.md - Complete guide to configuring AI providers
- AICEO_INTEGRATION_GUIDE.md - Integration with AICEO Gateway for centralized LLM access
- JENKINS.md - Jenkins CI/CD pipeline setup and configuration
RecursiveManager supports multiple AI providers with flexible configuration for both multi-perspective analysis and agent execution.
- AICEO Gateway (Recommended): Centralized rate-limited access with shared quota management across platforms
- Direct Anthropic: Direct API calls to Claude models
- Direct OpenAI: Direct API calls to GPT models
- GLM Direct: Direct API calls to GLM models
- Custom Providers: Support for custom LLM endpoints
Configure your AI provider via environment variables:
# Use AICEO Gateway (recommended for shared quota management)
export AI_PROVIDER=aiceo-gateway
export AICEO_GATEWAY_URL=http://localhost:4000/api/glm/submit
export AICEO_GATEWAY_API_KEY=your-shared-secret
export AICEO_GATEWAY_PROVIDER=glm
export AICEO_GATEWAY_MODEL=glm-4.7
# Or use direct Anthropic
export AI_PROVIDER=anthropic-direct
export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_MODEL=claude-sonnet-4-5
# Configure fallback provider
export AI_FALLBACK_PROVIDER=glm-direct
export GLM_API_KEY=your-glm-api-keyπ Read the full AI Provider Guide for detailed configuration, provider comparison, and troubleshooting.
RecursiveManager integrates seamlessly with AICEO's GLM Gateway to enable:
- Centralized Rate Limiting: Shared quota management across all platforms (AICEO, RecursiveManager, Slack bots, etc.)
- Priority Queue: High/normal/low priority request handling
- Cost Tracking: Centralized LLM API cost monitoring and analytics
- Automatic Failover: Falls back to direct providers if gateway unavailable
- Request Logging: Full audit trail of all LLM requests
-
Start AICEO Gateway:
cd /path/to/AICEO npm run dev -
Configure RecursiveManager:
export AI_PROVIDER=aiceo-gateway export AICEO_GATEWAY_URL=http://localhost:4000/api/glm/submit export AICEO_GATEWAY_API_KEY=your-shared-secret
-
Test Integration:
recursivemanager analyze "Should we implement Redis caching?"
π Read the full AICEO Integration Guide for step-by-step setup, testing, quota management, and monitoring.
Each agent has:
- Identity: Role, goal, capabilities
- Manager: Reports to another agent (except CEO)
- Subordinates: Can hire agents to delegate work
- Workspace: Personal directory for notes, tasks, research
- Continuous: Picks up next pending task, executes it, updates progress
- Reactive: Triggered by messages (Slack, Telegram, manager, etc.)
- Scheduled: Time-based triggers (daily standup, weekly review, etc.)
- Hierarchical: Tasks can nest indefinitely (with depth limits)
- Delegatable: Tasks can be assigned to subordinate agents
- Traceable: Full audit trail of all task changes
- Archivable: Completed tasks archived to prevent clutter
Before major decisions (hiring, firing, strategic changes), agents automatically trigger multi-perspective analysis using 8 specialized AI agents running in parallel:
The 8 Perspectives:
- Security: Identifies risks, vulnerabilities, and compliance issues
- Architecture: Analyzes scalability, maintainability, and technical debt
- Simplicity: Advocates for YAGNI principle and reducing complexity
- Financial: Evaluates costs, benefits, ROI, and resource utilization
- Marketing: Assesses positioning, messaging, and competitive advantage
- UX: Examines user experience, usability, and accessibility
- Growth: Considers adoption, retention, and virality
- Emotional: Evaluates team morale, user sentiment, and psychological impact
Example Usage:
# Manual analysis
recursivemanager analyze "Should we migrate to microservices?"
# Output: All 8 perspectives with confidence scores, synthesized decision
# βββββββββββββββ¬βββββββββββββ¬βββββββββββββββββββββββββββββ
# β Perspective β Confidence β Summary β
# βββββββββββββββΌβββββββββββββΌβββββββββββββββββββββββββββββ€
# β Security β 0.85 β Increases attack surface... β
# β Architectureβ 0.82 β Better scalability but... β
# β ... β ... β ... β
# βββββββββββββββ΄βββββββββββββ΄βββββββββββββββββββββββββββββResults are synthesized into a decision with overall confidence levels (accounting for agreement/disagreement between perspectives) and full reasoning. All analyses are cached and persisted to agent workspaces for audit trails.
Automatic Triggers:
- Before hiring a new agent
- Before firing an agent
- Before major configuration changes
- On-demand via CLI command
βββββββββββββββββββββββββββββββββββββββββββ
β CLI Tool β
β (User-facing interface) β
βββββββββββββ¬ββββββββββββββββββββββββββββββ
β
βββββββββββββΌββββββββββββββββββββββββββββββ
β Scheduler Daemon β
β (Time-based + event triggers) β
βββββββββββββ¬ββββββββββββββββββββββββββββββ
β
βββββββββββββΌββββββββββββββββββββββββββββββ
β Core Orchestrator β
β (Framework-agnostic execution) β
βββ¬ββββββββββ¬ββββββββββββββ¬ββββββββββββββββ
β β β
βββΌβββββββ ββΌβββββββββββ ββΌββββββββββββββ
β Claude β β OpenCode β β Future β
β Code β β β β Adapters β
ββββββββββ βββββββββββββ ββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββ
β Messaging Integration Layer β
β ββββββββββ ββββββββββ ββββββββββ β
β β Slack β βTelegramβ β Email β β
β ββββββββββ ββββββββββ ββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββ
βΌ
βββββββββββββββββββββββββββββββββββββββββββ
β File-Based State Storage β
β agents/{shard}/{agent-id}/ β
β βββ config.json β
β βββ schedule.json β
β βββ tasks/ β
β βββ inbox/ β
β βββ workspace/ β
βββββββββββββββββββββββββββββββββββββββββββ
Current Phase: Production Release (v1.0.0)
RecursiveManager is now PRODUCTION READY with all core phases complete. The system has undergone comprehensive testing, security hardening, and production deployment preparation.
β Core System
- Recursive agent hierarchy with manager-subordinate relationships
- File-based persistence with agent workspaces
- Multi-perspective analysis with real AI provider integration (8 perspectives)
- Decision synthesis with confidence levels and conflict detection
- Agent locking mechanisms using async-mutex
- ExecutionPool with worker pool pattern (configurable concurrency)
- PID file management for process tracking
- Test Coverage: 2337/2337 tests passing (100% pass rate)
β Multi-Provider AI Integration
- AICEO Gateway support (centralized rate limiting and quota management)
- Direct Anthropic API integration (Claude models)
- Direct OpenAI API integration (GPT models)
- GLM Direct API support
- Custom provider endpoints
- Automatic failover to backup providers
- Per-request provider override capability
β Advanced Task Execution
- Priority Queue System: Task priorities (low, medium, high, urgent)
- Dependency Management: Task dependency graph with cycle detection
- Resource Quotas: CPU, memory, and time limits per agent
- Execution Modes: Continuous, reactive (message-triggered), scheduled (cron)
- Worker Pool: Configurable max concurrent executions (default: 10)
- Queue Metrics: Wait time tracking and queue depth monitoring
β Security Hardening
- Database Encryption: AES-256-GCM authenticated encryption at rest
- Secret Management: Encrypted storage for API keys with audit logging
- Secret Rotation: Manual/automatic rotation policies with expiration tracking
- Audit Logging: Comprehensive security event tracking
- Input Validation: Request size limits and sanitization
- Dependency Scanning: Automated vulnerability scanning in CI/CD
- OWASP Coverage: Security tests for Top 10 vulnerabilities
β Snapshot & Disaster Recovery
- Automatic snapshots on agent hire/fire operations
- Manual snapshot creation via CLI
- Snapshot validation and integrity checking
- Interactive rollback with snapshot selection
- Backup creation before restoration
- Metadata tracking (ID, reason, timestamp, size, schema version)
β Monitoring & Observability
- Prometheus Metrics: 15+ metrics covering executions, queues, agents, resources
- Grafana Dashboards: 3 pre-built dashboards (Overview, Agent Performance, System Metrics)
- Alerting Rules: 13 comprehensive alert rules (error rates, resource usage, queue backlog, etc.)
- Structured Logging: JSON format with Winston, automatic rotation and compression
- Correlation IDs: Distributed tracing with trace IDs across all operations
- Log Levels: Configurable via environment variable (debug, info, warn, error)
- CLI Metrics Server:
recursivemanager metricscommand with/healthand/metricsendpoints
β Docker Production Deployment
- Multi-stage production Dockerfile (security scanning with Trivy)
- Non-root user execution (UID 1001)
- Docker Compose stack with Prometheus + Grafana
- Health checks and automatic restarts
- Volume management for data persistence
- Resource limits (configurable CPU/memory)
- Signal handling with dumb-init
β CLI Interface (13 Commands)
recursivemanager init- Initialize with goalrecursivemanager status- Show org chart and agent detailsrecursivemanager hire- Hire new agents (with multi-perspective analysis)recursivemanager fire- Fire agents (with automatic snapshot)recursivemanager message- Send messages to agents for reactive executionrecursivemanager run- Manually trigger agent executionrecursivemanager logs- View and filter agent logs with advanced searchrecursivemanager analyze- Run multi-perspective AI analysisrecursivemanager metrics- Start Prometheus metrics HTTP serverrecursivemanager update- Self-update system with rollbackrecursivemanager config- Configuration managementrecursivemanager debug- Agent debugging and inspectionrecursivemanager rollback- Restore from database snapshots
π Complete CLI Reference - Full documentation for all commands
β Installation & Updates
- One-liner installation script with headless mode
- Binary distribution for multiple platforms
- Self-update mechanism via GitHub API
- Version rollback capability
- Version history tracking
β Documentation
- Comprehensive website with VitePress
- Architecture documentation with system diagrams
- API reference documentation
- CLI reference with examples
- Development and contribution guides
- Monitoring and security guides
β CI/CD & Testing
- GitHub Actions workflows for CI, release, and docs
- Automated testing across Node.js 18, 20, 22
- Code coverage reporting with Codecov
- Turbo monorepo orchestration
- Automated dependency vulnerability scanning
- Release automation on version tags
- β Phase 1: Testing & Build Verification (2337/2337 tests passing)
- β Phase 2: Multi-Perspective AI Analysis (Real provider integration complete)
- β Phase 3: CLI Commands (All 13 commands implemented)
- β Phase 4: Scheduler Enhancements (Priority queue, dependencies, resource quotas)
- β Phase 5: Snapshot System (Full backup/restore with validation)
- β Phase 6: Security Hardening (Encryption, secrets, audit logging)
β οΈ Phase 7: Jenkins CI/CD (GitHub Actions active, Jenkins setup blocked)- β Phase 8: Docker Production Deployment (Multi-stage build, compose stack)
- β Phase 9: Monitoring & Metrics (Prometheus, Grafana, alerting)
- π Phase 10: Documentation (In progress - core docs complete)
- βΈοΈ Phase 11: Binary Distribution (Planned)
- βΈοΈ Phase 12: Post-Launch Verification (Planned)
See IMPLEMENTATION_PHASES.md for the full roadmap.
RecursiveManager is inherently complex (recursive hierarchies, multi-framework support, distributed state). We manage this complexity through:
- Progressive Disclosure: Simple by default, powerful when needed
- Clear Abstractions: Hide implementation details behind clean interfaces
- Excellent Documentation: Every feature explained with examples
- Smart Defaults: Works out-of-box for common use cases
- Actionable Errors: Error messages include suggested fixes
- Debugging Tools: Single-command insights into system state
- One-command start:
recursivemanager init "goal" - Convention over configuration: Sensible defaults everywhere
- Self-documenting: Files include README.md and comments
- Fail fast: Validate early, fail with clear messages
- Easy debugging:
recursivemanager debug <agent-id>shows everything
- Unit Tests: 80%+ coverage, fast feedback
- Integration Tests: Component interactions validated
- E2E Tests: Full user journeys tested
- Performance Tests: Scalability to 1000+ agents
- Edge Case Tests: Every contingency tested
See Edge Cases document for comprehensive edge case catalog.
# CEO hires CTO
# CTO hires Backend Dev, Frontend Dev, DevOps
# Each dev implements their piece
# CTO coordinates integration
# CEO reviews final product# CEO hires Content Strategist
# Strategist hires Writers, Editors, SEO Specialist
# Writers create content
# Editors review
# SEO optimizes
# Strategist publishes# CEO hires Data Scientist
# Data Scientist hires Data Engineer, ML Engineer
# Data Engineer builds pipeline
# ML Engineer trains models
# Data Scientist synthesizes insights# CEO hires Support Manager
# Support Manager monitors Slack/Email
# Escalates to specialists as needed
# Specialists resolve issues
# Support Manager follows upWe welcome contributions! See our Contributing Guide for details.
Ways to Contribute:
- Report bugs or suggest features via GitHub Issues
- Improve documentation
- Submit pull requests for bug fixes or features
- Share use cases and examples
- Help test edge cases
- GitHub Issues: Report bugs or request features
- GitHub Discussions: Ask questions and share ideas
- Documentation: Full documentation site
MIT License - see LICENSE for details
This project is inspired by:
- Ralph: The autonomous development loop concept
- AICEO: The multi-agent analysis approach
- Real organizations: How businesses actually delegate and coordinate
- GitHub: RecursiveManager
- Issues: Report bugs or request features
- Documentation: https://aaron777collins.github.io/RecursiveManager/
Version: 1.0.0 (Production) Status: Production Ready - comprehensive testing, security hardening, monitoring, and deployment complete Philosophy: Quality over cost. Multi-perspective analysis. Stateless execution. Business-like structure. Goal: Enable AI agents to coordinate like real organizations, handling complex, long-running projects autonomously.