OpenNexum

Contract-driven coding agent orchestration via OpenClaw ACP.

When to use

• Coordinating multiple AI coding agents (Codex + Claude)
• Running generator/evaluator pairs with automatic retry and escalation
• Parallel task execution with independent ACP sessions
• Tracking task progress with OpenClaw notifications

Architecture

Dispatch (dual-path)

1. Webhook (real-time): nexum callback → POST /hooks/agent → orchestrator wakes up immediately
2. Dispatch Queue (fallback): nexum callback → writes nexum/dispatch-queue.jsonl → heartbeat processes within 10min

Cross-review

• codex-gen → claude-eval, claude-gen → codex-eval

Auto-routing

• generator: auto in Contract YAML → system selects agent by task type

Batch progress

• nexum status shows current batch progress + overall progress

Agent Naming: <model>-<role>-<number>

• codex-gen-01~03: backend/API code
• claude-gen-01~02: user-facing WebUI/docs
• codex-eval-01 / claude-eval-01: cross-review
• claude-plan-01: architecture (opus)

Key CLI Commands

nexum init [--project <dir>] [--yes]
nexum sync [taskId] [--project <dir>]
nexum spawn <taskId> [--project <dir>]
nexum track <taskId> <sessionKey>
nexum callback <taskId> [--role evaluator] [--model gpt-5.4] [--input-tokens N] [--output-tokens N]
nexum eval <taskId>
nexum complete <taskId> <pass|fail|escalated>
nexum status [--project <dir>]
nexum archive [--project <dir>]
nexum health [--project <dir>]
nexum retry <taskId> --force

Contract YAML

id: TASK-001
name: "implement feature X"
batch: batch-1
agent:
  generator: codex-gen-01
  evaluator: claude-eval-01
scope:
  files:
    - src/feature.ts
deliverables:
  - path: src/feature.ts
    description: "..."
eval_strategy:
  type: review
  criteria:
    - id: C1
      desc: "..."
      weight: 2
max_iterations: 3

Callback Protocol (injected into AGENTS.md via nexum init)

nexum init writes the callback protocol into AGENTS.md as the source of truth. If a project only has CLAUDE.md, Nexum will seed AGENTS.md from it and update AGENTS.md going forward.

After completing a task, run:

nexum callback <taskId> --project <projectDir> \
  --model gpt-5.4 \
  --input-tokens <n> \
  --output-tokens <n>

Git Convention

• Push directly to main, revert if needed
• English Conventional Commits: feat(scope): TASK-ID: description