Claude Nexus

Persistent task DAG orchestration for AI coding agents. Break down complex goals into sized, dependency-aware tasks — routed to the right model, tracked across sessions, resumable after crashes.

What It Does

Claude Nexus manages a recursive task hierarchy backed by SQLite:

• Projects hold a goal and a tree of tasks
• Tasks have a kind (project/milestone/task/subtask) and size (S/M/L/XL) that determines model routing
• Dependencies form a DAG — tasks auto-promote to ready when their dependencies complete
• Persistence — the entire DAG survives crashes, restarts, and session switches
• Oracle — the coordinator session's LLM decomposes goals, sizes tasks, and spawns agents

Size → Model Routing

| Size | Model | Use for | |------|-------|---------| | S | Haiku | Lookups, simple edits | | M | Sonnet | Standard implementation | | L | Opus | Architecture, deep analysis | | XL | Decompose first | Too large — break it down |

Install

npm install -g cnexus
cnexus setup   # auto-configures Claude Code MCP integration

Or from source

git clone https://github.com/doyonghoon/claude-nexus.git
cd claude-nexus
npm install
npm run build
cnexus setup

Quick Start (Claude Code)

After cnexus setup, the MCP tools are available in any Claude Code session. The workflow:

1. Create a project with a goal
2. The oracle decomposes it into a plan (task tree)
3. You approve the plan → tasks are created in the DAG
4. Execute ready tasks → agents are spawned with the right model
5. Complete/fail tasks → dependents auto-promote to ready
6. Resume anytime — state persists in SQLite

Example conversation

You: "Create a project to migrate our auth service to OAuth2"
→ nexus_create_project creates project + root task

You: "What's the plan?"
→ nexus_plan returns a structured decomposition prompt
→ Oracle proposes: 3 milestones, 8 tasks, sized S-L

You: "Approve it"
→ nexus_approve materializes the plan into the DAG

You: "Execute"
→ nexus_execute finds ready tasks, returns spawn instructions with prompts

You: "Task X is done, here's the result"
→ nexus_complete_v2 marks it done, promotes dependents to ready

You: "How are we doing?"
→ nexus_status shows the full tree with progress

[... close session, come back tomorrow ...]

You: "Resume the auth migration"
→ nexus_resume loads the DAG, runs promotion, shows what's ready

MCP Tools

Project lifecycle:

| Tool | Description | |------|-------------| | nexus_create_project | Create a project with a goal → root task | | nexus_list_projects | List projects with task summaries | | nexus_resume | Load a project, promote ready tasks, show status | | nexus_plan | Get a structured prompt for the oracle to decompose | | nexus_approve | Approve a plan → create tasks in the DAG | | nexus_adapt | Get a prompt to adjust the plan mid-flight |

Task execution:

| Tool | Description | |------|-------------| | nexus_execute | Find ready tasks, return spawn instructions with model/prompt | | nexus_complete_v2 | Mark task done with result, auto-promote dependents | | nexus_fail_v2 | Mark task failed with reason, auto-retry if under limit | | nexus_status | Full project tree with summary counts | | nexus_result_v2 | Get a task's result | | nexus_review | Get a structured review prompt for acceptance criteria | | nexus_add_context | Attach file references to a task | | nexus_cost | Cost breakdown by model and task |

MCP Setup

Auto-setup (recommended):

cnexus setup

Manual — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "cnexus": {
      "command": "cnexus-mcp",
      "args": []
    }
  }
}

Task Lifecycle

pending → ready → assigned → in-progress → complete
                                          → failed → pending (retry)
                                          → cancelled

• pending — waiting for dependencies
• ready — all dependencies complete, eligible for assignment
• assigned — claimed by an agent (optimistic locking prevents races)
• in-progress — agent is executing
• complete — done, dependents auto-promoted
• failed — auto-retries up to max_retries, then stays failed

CLI

The CLI provides an escape hatch for operations outside Claude Code:

# Getting started
cnexus setup                        # Configure MCP integration
nexus quickstart <prompt> -w 3      # One-liner: init + decompose + run

# Orchestration
nexus init [--name]                 # Initialize coordinator
nexus join [--auto] [--role]        # Join as worker
nexus run <plan.yaml>               # Execute a YAML plan

# Monitoring
nexus status                        # Nodes and tasks
nexus dashboard                     # Live TUI
nexus cost [--by engine|task|node]  # Cost tracking
nexus logs [--node] [--task]        # Event log
nexus trace <task-id>               # Task timeline

Multi-Engine Support

cnexus routes tasks to different LLM engines:

| Engine | Model | Best for | Cost | |--------|-------|----------|------| | claude | Claude Sonnet 4.6 | Complex reasoning, code generation | $$$ | | gemini | Gemini 2.5 Flash | Fast analysis, bulk diagnosis | $ | | codex | GPT-4o | General purpose | $$ |

Set ANTHROPIC_API_KEY, GEMINI_API_KEY, and/or OPENAI_API_KEY to enable engines.

Cross-Machine Orchestration

# Machine A (coordinator)
cnexus serve --port 7400

# Machine B (worker)
nexus worker --coordinator http://machine-a:7400

Architecture

┌─────────────────────────────────────────────┐
│              Coordinator Session             │
│                                              │
│  Oracle (LLM)  ──→  Decompose goals         │
│       │              Size tasks (S/M/L/XL)   │
│       │              Route to models         │
│       ▼                                      │
│  ┌──────────┐    ┌──────────┐               │
│  │ Projects  │    │  Plans   │               │
│  └──────────┘    └──────────┘               │
│       │               │                      │
│       ▼               ▼                      │
│  ┌────────────────────────────┐             │
│  │     Task DAG (SQLite)      │             │
│  │  kind: project/milestone/  │             │
│  │        task/subtask        │             │
│  │  size: S → Haiku           │             │
│  │        M → Sonnet          │             │
│  │        L → Opus            │             │
│  │        XL → decompose      │             │
│  └────────────────────────────┘             │
│       │                                      │
│       ▼                                      │
│  Agent Spawner ──→  Subagents with prompts   │
│                     (isolated per task)       │
└─────────────────────────────────────────────┘
         │
    SQLite WAL ──→ survives crashes, session switches

Persistence: SQLite3 with WAL mode. Tables: projects, tasks, plans, agent_runs, nodes, documents, messages, cost_events, traces.

Development

git clone https://github.com/doyonghoon/claude-nexus.git
cd claude-nexus
npm install
npm run build

Scripts

npm run dev          # Run CLI in dev mode (tsx)
npm run build        # Build with tsup
npm test             # Run tests (vitest) — 687 tests
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint

Project Structure

src/
├── agent/        # Prompt builder for spawned agents
├── app/          # NexusApp composition root
├── cli/          # CLI commands (commander)
├── core/         # Coordinator and worker roles
├── db/           # SQLite3 schema, migrations, repositories
├── extensions/   # Engine adapters (Claude, Gemini, OpenAI) + transport
├── mcp/          # MCP server, v2 tool handlers, HTTP bridge
├── oracle/       # Router (size→model), Introspector (env detection)
├── task/         # Task lifecycle, DAG scheduling, dependency promotion
├── traces/       # Observability spans, cost tracking
└── types/        # Shared TypeScript types

License

MIT