APEX Orchestrator

Autonomous Parallel EXecution — an AI-powered development orchestrator for large codebases. Takes a task in natural language, decomposes it into subtasks, executes them in parallel via LLM-powered workers, validates results, and commits changes.

---

🎯 Recent Updates (Feb 2026)

Git Changes UI ✅

• Real-time monitoring of git status, branches, commits
• Interactive diff viewer with split-view
• Stash management (create/pop/apply/drop)
• Branch operations (checkout, delete, compare)

Database Management ✅

• Database size monitoring (auto-refresh every 5s)
• Checkpoint cleanup strategies (keep_final_only, keep_last_n)
• Thread details view with checkpoint counts
• Reduced DB from 12GB to 0.11MB after cleanup

Graph Editor ✅

• Review mode with manual approve/reject
• Subtask editing (add/delete/reorder)
• Wave reorganization with drag & drop
• AI suggestions (fix_deps, optimize_waves, split, merge)
• Undo/redo with 50-entry history

---

📚 Documentation

• 🚀 Getting Started — Set up and run your first task in 5 minutes
• 🔧 Integration Guide — Three ways to integrate APEX into your project
• 💻 Command Reference — Complete CLI and API reference

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                     Docker Compose                       │
├──────────────────────────────────────────────────────────┤
│  sharp_eye UI (:7353)                                    │
│  React 19 + Ant Design + React Flow + SSE                │
│  │  REST + SSE                                           │
│  ▼                                                       │
│  big_brain Orchestrator (:7352)                          │
│  Python 3.12 + LangGraph + FastAPI + OpenHands SDK       │
│  │  LangGraph: ANALYZE → DECOMPOSE → EXECUTE →          │
│  │             VALIDATE → COMMIT                         │
│  │  Workers = OpenHands Conversation (per git worktree)  │
│  │  LLM = LiteLLM → OpenRouter                          │
│  │  Routing = RouteLLM (workers) + Sonnet (orchestrator) │
│  │              │                                        │
│  │ MCP(HTTP)    │ HTTP                                   │
│  ▼              ▼                                        │
│  quick_hands    Qdrant (:7350)                           │
│  MCP (:7351)    code, docs, history vectors              │
└──────────────────────────────────────────────────────────┘

Components

Component	Path	Stack	Purpose
big_brain	src/big_brain/	Python 3.12, LangGraph, FastAPI	Orchestrator core — graph, nodes, API, context engine
sharp_eye	src/sharp_eye/	React 19, Ant Design, React Flow	Dashboard UI — task management, run history, graph editor
quick_hands	src/quick_hands/	Node.js, TypeScript	MCP server — 16 code scaffolding tools

Graph Flow

START → analyze → decompose → execute → worker(s) → validate → commit → END
                                  ↑                      │
                                  └── retry (on failure) ─┘

• analyze — gathers context from codebase via RAG (Qdrant) and MCP tools
• decompose — breaks task into subtasks with dependency waves (LiteLLM → Sonnet)
• execute — creates git worktrees per subtask, dispatches parallel workers
• worker — executes subtask via OpenHands SDK (FileEditor + Terminal tools)
• validate — checks success, file existence, Python syntax, LLM code review
• commit — creates git commit with all changes

Tech Stack

Layer	Technology
Graph engine	LangGraph (StateGraph with checkpointing)
Worker execution	OpenHands SDK (openhands-sdk + openhands-aci)
LLM abstraction	LiteLLM (unified API for 100+ providers)
Model routing	RouteLLM (automatic strong/weak model selection)
Embeddings	FastEmbed (sentence-transformers/all-MiniLM-L6-v2, ONNX)
Vector DB	Qdrant (code, docs, history collections)
API	FastAPI (REST + SSE streaming)
UI	React 19, Refine, Ant Design, React Flow
MCP Server	Node.js TypeScript (16 scaffolding tools)
Isolation	Git worktrees (one per parallel worker)

Quick Start

Prerequisites

• Docker and Docker Compose
• OPENROUTER_API_KEY environment variable set

Run with Docker Compose

# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f orchestrator

Run with Just

# Start system
just orch-up

# Run a task
just orch-run "Add description field to Tag model"

# Index codebase into Qdrant
just orch-index

# View logs
just orch-logs orchestrator

# Stop
just orch-down

CLI Usage

# Full execution
python -m big_brain "Add CRUD endpoints for Playlist"

# Dry run (analyze + decompose only)
python -m big_brain "Refactor auth module" --dry-run

# Verbose logging
python -m big_brain "Fix N+1 query in users page" --verbose

Services & Ports

Service	Container	Port	Health Check
Qdrant	orchestrator-qdrant	:7350	GET /readyz
MCP Server	orchestrator-hands	:7351	GET /health
Orchestrator API	orchestrator-brain	:7352	GET /health
UI	orchestrator-eye	:7353	GET /

API Endpoints

Route	Description
Core
GET /health	Health check
POST /tasks	Create a new task (with optional require_review)
GET /tasks	List tasks
GET /tasks/{id}	Get task details
POST /runs	Start a task run
GET /runs	List runs
GET /runs/{id}	Get run details
GET /stream/{run_id}	SSE stream for run progress
GET /skills	List available skills
GET /stats	Get usage statistics
GET /graph	Get graph structure
Graph Editor
POST /tasks/{id}/approve	Approve/reject plan
PUT /tasks/{id}/subtasks/{sid}	Update subtask
POST /tasks/{id}/subtasks	Create subtask
DELETE /tasks/{id}/subtasks/{sid}	Delete subtask
PUT /tasks/{id}/waves	Reorganize waves
Database
GET /database/stats	Database size, checkpoints, threads
GET /database/details	Thread list with checkpoint counts
POST /database/cleanup	Cleanup old checkpoints
Git Operations
GET /git/status	Git status (branch, files, ahead/behind)
GET /git/diff/{file}	Unified diff for file
GET /git/branches	List all branches
GET /git/commits	Commit history
GET /git/branch-diff	Changes in branch vs base
POST /git/checkout	Switch branch
DELETE /git/branches/{name}	Delete branch
GET /git/stash/list	List stash entries
POST /git/stash/push	Create stash
POST /git/stash/pop	Pop stash
POST /git/stash/apply	Apply stash
DELETE /git/stash/drop	Drop stash

Configuration

All configuration is via environment variables with sensible defaults:

Variable	Default	Description
OPENROUTER_API_KEY	—	OpenRouter API key (required)
OPENROUTER_BASE_URL	https://openrouter.ai/api/v1	OpenRouter base URL
ORCHESTRATOR_MODEL	anthropic/claude-sonnet-4-20250514	Model for orchestrator nodes
WORKER_MODEL	anthropic/claude-haiku-4-5-20241022	Default worker model
WORKER_CHEAP_MODEL	deepseek/deepseek-chat	Cheap model for simple tasks
WORKER_LARGE_CTX_MODEL	google/gemini-2.5-pro-preview-06-05	Large context model
OPENHANDS_MAX_STEPS	30	Max agent steps per subtask
WORKER_PARALLEL_LIMIT	4	Max parallel workers per wave
ROUTELLM_THRESHOLD	0.5	Routing threshold (0=cheap, 1=strong)
ROUTELLM_STRONG_MODEL	anthropic/claude-sonnet-4-20250514	Strong model for routing
ROUTELLM_WEAK_MODEL	deepseek/deepseek-chat	Weak model for routing
QDRANT_URL	http://localhost:6333	Qdrant server URL
MCP_SERVER_URL	http://localhost:3000	MCP server URL
WORKSPACE_ROOT	/workspace	Workspace root path
EMBEDDING_MODEL	sentence-transformers/all-MiniLM-L6-v2	FastEmbed model (384 dimensions)

Project Structure

apex/
├── src/
│   ├── big_brain/              # Orchestrator (Python)
│   │   ├── api/                # FastAPI routes
│   │   │   ├── app.py          # Application setup
│   │   │   └── routes/         # tasks, runs, skills, stats, stream, graph
│   │   ├── graph/              # LangGraph
│   │   │   ├── state.py        # OrchestratorState, SubTask, WorkerResult
│   │   │   ├── builder.py      # Graph construction
│   │   │   └── nodes/          # analyze, decompose, execute, worker, validate, commit
│   │   ├── workers/            # Worker execution layer
│   │   │   ├── openhands_worker.py  # OpenHands SDK integration
│   │   │   ├── git_isolation.py     # Git worktree management
│   │   │   └── routing.py          # RouteLLM model selection
│   │   ├── context/            # Context engine
│   │   │   ├── engine.py       # Context gathering
│   │   │   ├── rag.py          # Qdrant vector search
│   │   │   ├── indexer.py      # Codebase indexer with embeddings
│   │   │   └── mcp_client.py   # MCP server client
│   │   ├── prompts/            # LLM prompt templates
│   │   ├── skills/             # Project knowledge files
│   │   └── config.py           # Pydantic configuration
│   ├── sharp_eye/              # UI (React)
│   │   ├── src/
│   │   │   ├── pages/          # Dashboard, graph editor
│   │   │   ├── resources/      # Tasks, runs, skills CRUD
│   │   │   ├── components/     # CostBadge, LiveLogStream, StatusTag
│   │   │   └── providers/      # Data provider, live provider
│   │   └── vite.config.ts
│   └── quick_hands/            # MCP Server (Node.js)
│       └── src/tools/          # Backend, frontend, operations tools
├── dockerfiles/                # Dockerfile.orchestrator, .orchestrator-ui, .mcp-server
├── docker-compose.yaml         # 4 services: qdrant, mcp, orchestrator, ui
├── justfile                    # Build/run recipes
├── requirements.txt            # Python dependencies
└── plans/                      # Design documents