Unified AI coding agent orchestration with subscription-first routing

Features • Installation • Quick Start • Configuration • Commands • Deployment • Architecture

ADO (Agentic Development Orchestrator) is a TypeScript CLI tool that orchestrates multiple AI coding agents (Claude Code, Gemini CLI, Cursor CLI, GitHub Copilot, Codex) behind a unified interface with advanced autonomous workflow capabilities.

Key Innovation: Subscription-first routing prioritizes subscription-based access (Claude MAX, Cursor Pro, etc.) over API billing to maximize value from existing subscriptions.

• 🎯 Unified Interface - Single CLI for multiple AI coding agents
• 💰 Subscription-First - Maximize subscription value before API fallback
• 🔄 Automatic Failover - Seamless switching when rate limits hit
• 📊 Usage Tracking - Monitor costs and usage across providers
• 💾 State Persistence - Resume sessions, track history
• 🎨 Beautiful CLI - Interactive prompts and colorful output

• 🧠 Task Decomposition - Breaks complex tasks into subtasks with checkpoints
• 📝 Specification Generation - Doc-first workflow (/specify → /plan → /tasks → /implement)
• ✅ Quality Validation - Multi-language build, test, lint validation (≥80% coverage)
• 🔧 Auto-Fix Engine - Automatic error fixing with stuck detection
• 🤝 HITL Checkpoints - Human-in-the-loop at critical points (5 iterations / 30 min thresholds)
• 🔄 Recovery System - Automatic retry, rollback, and restore

• 🌐 Remote Workers - Distributed task execution via K8s
• 📡 tRPC + WebSocket - Type-safe API with real-time updates
• 🗄️ State Synchronization - PostgreSQL-based distributed state
• 💓 Health Monitoring - Automatic worker health checks

• ⚡ Parallel Scheduler - DAG-based parallel task execution
• 🌳 Git Worktree Isolation - Isolated work per parallel agent
• 📈 Auto-Scaling - Kubernetes HPA for dynamic worker pools
• 💵 Cost-Aware Load Balancing - Optimize for cost, performance, or balance
• 🤖 AI-Powered Merging - 80%+ automatic conflict resolution

• 🌐 Web Dashboard - Real-time task monitoring and analytics (React 18)
• 📬 Notifications - Slack and email alerts for task events
• 🔍 Observability - OpenTelemetry integration for tracing and metrics
• ☸️ Kubernetes Ready - Deploy locally or on K8s with same interface
• 🔐 Security - Firecracker sandboxing (125ms startup, planned)

• 🔀 LiteLLM Routing - 100+ LLM providers with fallback chains
• 💰 Cost Optimization - Multi-provider cost tracking and forecasting
• 🔁 Durable Workflows - Temporal.io integration (planned)
• 🔍 PR-Agent - Automated code review (/describe, /review, /improve, planned)

# Install globally
npm install -g @dxheroes/ado

# Or use with npx
npx @dxheroes/ado init

• Node.js 22+
• pnpm 9.x (recommended package manager)
• At least one AI coding agent installed:
  • Claude Code - npm install -g @anthropic-ai/claude-code

# Initialize ADO in your project
ado init

# Run a task locally
ado run "Implement user authentication with JWT"

# Check status
ado status

Deploy workers once, whole team benefits:

# 1. Deploy workers to Coolify (one-time setup by DevOps)
# See: docs/COOLIFY_DEPLOYMENT.md

# 2. Each developer configures local CLI
cat > ~/.ado/config.yaml <<EOF
remote:
  enabled: true
  apiUrl: https://ado.yourcompany.com
  defaultMode: hybrid
  auth:
    type: api_key
    keyEnvVar: ADO_API_KEY
EOF

echo "ADO_API_KEY=your-api-key" > ~/.ado/.env

# 3. Run tasks with powerful remote workers
ado run "Implement authentication" --hybrid
# ✨ Your code stays local, execution happens on cloud workers!

Execution Modes:

• Local - Everything on your laptop (default for solo devs)
• Hybrid ⭐ - Code local, execution remote (best for teams)
• Remote - Everything on cloud (for CI/CD)

See Execution Modes | Quick Start Guide | Coolify Deployment

ADO uses a YAML configuration file (ado.config.yaml) in your project root:

version: "1.1"

project:
  id: "my-project"

providers:
  claude-code:
    enabled: true
    accessModes:
      - mode: subscription
        priority: 1
        enabled: true
        subscription:
          plan: "max"
          rateLimits:
            requestsPerDay: 500

routing:
  strategy: "subscription-first"
  apiFallback:
    enabled: false

checkpoints:
  enabled: true
  autoSave: true
  escalationThresholds:
    maxIterations: 5
    maxDuration: 1800000  # 30 minutes

parallelization:
  enabled: false
  maxWorkers: 5
  costStrategy: "minimize-cost"  # or "balanced", "maximize-performance"

See ado.config.example.yaml for a complete configuration reference.

# Execute a task
ado run <prompt>

# Show current status
ado status

# Run workflow from file
ado workflow run <file>

# List workflows
ado workflow list

# Validate workflow definition
ado workflow validate <file>

# Show current configuration
ado config show

# Set configuration value
ado config set <key> <value>

# Interactive provider configuration (legacy)
ado config providers

# Start web dashboard (runs on port 3000)
ado dashboard

# Test Slack notification
ado notify slack

# Test email notification
ado notify email

# Test webhook notification
ado notify webhook

# Generate compliance report
ado report

# Initialize ADO in project (legacy - manual setup recommended)
ado init
ado init -y           # Accept defaults
ado init -f           # Overwrite existing

ADO's key innovation is prioritizing subscription-based access:

Task → Enabled Providers → Check Capabilities
                              ↓
                    Sort by Access Priority
                              ↓
              Subscription (1) → API Fallback (10)
                              ↓
                    Check Rate Limits
                              ↓
              Available? → Execute Task
                    ↓
              Limited? → Try Next Provider

This ensures you get maximum value from subscriptions like Claude MAX before falling back to pay-per-token APIs.

ADO is organized as a pnpm monorepo with 7 packages:

• @dxheroes/ado-core - Orchestration engine (21 modules, ~21K LoC)
• @dxheroes/ado-cli - CLI application
• @dxheroes/ado-adapters - Agent adapters (Claude, Gemini, Cursor, etc.)
• @dxheroes/ado-shared - Shared types and utilities
• @dxheroes/ado-dashboard - React web dashboard
• @dxheroes/ado-api - tRPC API server
• @dxheroes/ado-mcp-server - Model Context Protocol server

Core:

• TypeScript 5.x with strict mode
• Node.js 22 LTS
• pnpm 9.x (package manager)
• Biome (linting/formatting)
• Vitest (testing)

API & Communication:

• tRPC (type-safe RPC)
• WebSocket subscriptions
• REST endpoints

Frontend:

• React 18
• Vite
• Tailwind CSS
• TanStack Query
• Recharts

Database:

• SQLite (local development)
• PostgreSQL (Kubernetes deployment)
• Redis (rate limiting, planned)

Infrastructure:

• Docker
• Kubernetes + Helm charts
• Coolify support

LLM & AI:

• LiteLLM (100+ provider routing, planned)
• Temporal.io (durable workflows, planned)
• PR-Agent/Qodo Merge (code review, planned)

Security:

• Firecracker MicroVMs (sandboxing, planned)

Observability:

• OpenTelemetry
• Prometheus metrics
• Distributed tracing

ado/
├── packages/
│   ├── shared/         # Shared types and utilities
│   ├── core/           # Core orchestration engine (21 modules)
│   │   ├── src/
│   │   │   ├── autonomous/      # Task decomposition, spec generation, HITL
│   │   │   ├── parallel/        # Parallel execution, worker pools, cost optimization
│   │   │   ├── workflow/        # Workflow engine, Temporal.io integration
│   │   │   ├── worker/          # Worker management, K8s spawning, Firecracker
│   │   │   ├── llm/             # LiteLLM router (100+ providers)
│   │   │   ├── orchestrator/    # Core orchestration engine
│   │   │   ├── provider/        # Provider management
│   │   │   ├── notifications/   # Slack/Email/Webhook notifications
│   │   │   ├── telemetry/       # OpenTelemetry integration
│   │   │   ├── deployment/      # Context switching (local/K8s)
│   │   │   ├── cost/            # Cost tracking
│   │   │   ├── rate-limit/      # Rate limit detection
│   │   │   ├── state/           # State persistence (SQLite/PostgreSQL)
│   │   │   ├── config/          # Configuration management
│   │   │   ├── context/         # Project context
│   │   │   ├── execution/       # Worktree execution
│   │   │   ├── hitl/            # Human-in-the-loop
│   │   │   ├── queue/           # Task queue
│   │   │   ├── checkpoint/      # Checkpoint management
│   │   │   └── streaming/       # Progress streaming
│   ├── adapters/       # Agent adapters (Claude, Gemini, Cursor, etc.)
│   ├── cli/            # CLI application
│   ├── dashboard/      # Web dashboard (React + Tailwind)
│   ├── api/            # tRPC API server
│   └── mcp-server/     # MCP server
├── deploy/             # Kubernetes manifests, Helm charts
├── spec/               # Specification (67 documents)
├── docs/               # Comprehensive documentation
├── ado.config.yaml     # Example configuration
└── README.md

ADO uses context files to provide project information to AI agents:

• CLAUDE.md - Context for Claude Code
• AGENTS.md - Project structure and conventions for all agents
• .cursor - Context for Cursor
• .github/copilot-instructions.md - Context for Copilot

These files are automatically created during ado init and can be customized.

# Clone repository
git clone https://github.com/dxheroes/ado
cd ado

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Type checking
pnpm typecheck

# Linting
pnpm lint

• Quick Start (5 min) - Get running fast
• Getting Started Guide - Complete walkthrough
• Documentation Hub - All documentation organized by role

• Installation Guide
• Configuration Reference
• Provider Setup
• Troubleshooting

• API Reference
• Web Dashboard
• Notifications
• Kubernetes Deployment
• Error Codes

• Contributing Guide
• Code of Conduct
• Specification v2.1.0
• Compliance Report (95%)
• Project Context for AI Agents

ADO has achieved 95% compliance with the technical specification v2.1.0:

✅ Milestone 1-6: Complete (Production-Ready)

• M1-M3: MVP, Subscription-First Routing, Multi-Agent Support
• M5: Kubernetes Deployment (Helm charts, Docker images)
• M6: Production Polish (Dashboard, Notifications, Telemetry)

🚧 Milestone 7-9: Specification Complete, Implementation Planned

• tRPC + WebSocket API
• Remote worker management
• State synchronization (PostgreSQL)
• Worker health monitoring
• K8s worker spawning

• Task decomposition & classification
• Doc-first pipeline (/specify → /plan → /tasks → /implement)
• HITL checkpoints (5 iterations, 30 min thresholds)
• Quality validation (build, test, lint, coverage ≥80%)
• Auto-fix engine with stuck detection
• Recovery & escalation system

• Parallel scheduler (DAG-based)
• Git worktree isolation
• K8s auto-scaling (HPA)
• Cost-aware load balancing (minimize-cost, balanced, maximize-performance)
• Work stealing algorithm
• AI-powered merge coordinator (80%+ auto-resolution)
• Cost optimizer with forecasting

• LiteLLM Integration - 100+ LLM providers with fallback chains
• Temporal.io Workflows - Durable execution with HITL signals
• Firecracker Sandboxing - 125ms startup, 5MB overhead, full isolation
• PR-Agent Integration - Auto-review, auto-improve, changelog generation

• 109 passing tests across 10 test suites
• Core business logic: Excellent coverage (provider registry, router, rate limits, cost tracking)
• Integration layer: Limited coverage (CLI commands, adapters need tests)
• See SPECIFICATION-COMPLIANCE-GAPS.md for detailed gap analysis

Ready for:

• ✅ Single-user local development
• ✅ Team development with shared configuration
• ✅ CI/CD integration via CLI
• ✅ Web dashboard monitoring
• ✅ Multi-channel notifications
• ✅ OpenTelemetry observability

Pending for enterprise:

• 🚧 Full M7-M9 implementation (specifications complete)
• 🚧 Temporal.io durable workflows
• 🚧 Firecracker sandboxing
• 🚧 LiteLLM routing (100+ providers)
• 🚧 Multi-tenancy and RBAC (future milestone)

See Specification v2.1.0 and SPECIFICATION-COMPLIANCE-GAPS.md for the full compliance review.

# Pull latest images
docker pull dxheroes/ado:latest
docker pull dxheroes/ado-api:latest
docker pull dxheroes/ado-dashboard:latest

# Or from GitHub Container Registry
docker pull ghcr.io/dxheroes/ado:latest

See Docker Deployment Guide for detailed instructions and Release Workflow for image publishing details.

pnpm install
pnpm build
pnpm --filter @dxheroes/ado-cli dev

# Install with Helm
helm install ado ./deploy/helm/ado

# Or use kubectl
kubectl apply -f ./deploy/k8s/

docker-compose up -d

MIT © DX Heroes

Contributions are welcome! Please read our Contributing Guide and Code of Conduct before submitting a PR.

See also:

• Development Setup
• Coding Standards
• Testing Guide