conductor

Multi-agent orchestrator with eval-gated quality gates. Spawn parallel agent workers per track, verify output before merging.

Local multi-agent tools like Octogent are compelling — parallel workers, visible progress, git isolation. But they share the same fatal flaw: workers run until they say they're done, with no way to know if the output is actually correct. Sessions die when you close the terminal. There's no retry, no quality gate, no remote control.

conductor is what that category of tool looks like when built for real work. It uses evalgate as its quality gate layer — workers can't merge until their verifier passes.

How it works

You organize your project into tracks — scoped areas of ownership, each with a CONTEXT.md (what this area owns) and a todo.md (eval-gated tasks).

.conductor/
  config.json
  tracks/
    auth/
      CONTEXT.md      ← what this track owns + constraints
      todo.md         ← eval-gated tasks for this area
    payments/
      CONTEXT.md
      todo.md

Each task in todo.md follows the evalgate contract format:

- [ ] Add JWT validation middleware
  - eval: `npm test -- --testPathPattern=auth`
  - retries: 2

- [ ] Write integration tests for /login
  - eval: `npm run test:integration`

When you run conductor run auth, it spawns one agent worker per pending task — each in its own git worktree. A worker's changes only merge back to main when the eval: verifier exits 0.

Install

npm install -g conductor-agents

Or run directly:

npx conductor-agents help

Quick start

# 1. Initialize in your repo
cd your-project
git init  # must be a git repo with at least one commit
git commit --allow-empty -m "init"  # if starting from scratch
conductor init

# Option A — generate a plan from a goal (v0.5+)
conductor plan "add JWT authentication with middleware and login endpoint"
# Review .conductor/plan-draft.md, then:
conductor plan apply

# Option B — add tracks manually
conductor add auth --desc="Authentication layer" --files="src/auth/**"
# Edit .conductor/tracks/auth/todo.md with your tasks

# 2. Run
conductor run auth         # single track
conductor run --all        # all tracks — DAG order, parallel where possible

# 3. Check results
conductor status auth

CLI reference

conductor add options

--desc="description"                    Track description
--files="src/auth/**,src/users/**"      Owned file globs (comma-separated)
--depends="auth,payments"               Tracks this track depends on (comma-separated IDs)
--max-usd=<n>                           Budget cap in USD; pauses new workers and fires Telegram alert when exceeded
--max-tokens=<n>                        Budget cap in total tokens; same breach behavior as --max-usd

conductor run options

--concurrency=N        Worker concurrency (default: 3)
--agent=cmd            Agent command (default: claude) — inline flags are supported
--resume               Resume from existing state, skip done workers

The --agent flag (and the agentCmd field in config.json) supports inline flags. conductor splits the string automatically so Node's spawn receives the binary and args separately:

conductor run auth --agent="claude --dangerously-skip-permissions"

{
  "defaults": {
    "agentCmd": "claude --dangerously-skip-permissions"
  }
}

conductor logs options

--follow, -f           Tail the log live (polls every 500ms until Ctrl+C)

Worker IDs can be abbreviated — any unique prefix works:

conductor logs eb2eadd4 auth
conductor logs eb2eadd4 auth --follow

Task format

Tasks live in .conductor/tracks/<name>/todo.md and follow the evalgate contract format:

- [ ] Task title
  - eval: `shell verifier command`
  - retries: 2

The verifier command runs inside the worker's git worktree after the agent finishes. Exit 0 = merge. Anything else = fail (and retry if retries remain).

Requirement: the repository must have at least one commit before running workers. evalgate creates per-worker branches from HEAD — if there is no commit yet, the merge step will fail. Run git commit --allow-empty -m "init" if starting from a fresh git init.

Run outcomes are recorded in the track's history:

• PASS — verifier exited 0 and the git merge committed the work back to main.
• FAIL — verifier definitively exited non-zero. Workers that pass the verifier but fail at merge are not recorded — the work wasn't committed.

Composite verifiers are supported:

- [ ] Build, lint, and test all pass
  - eval.all: `npm run build` | `npm run lint` | `npm test`

- [ ] README is clear
  - eval.llm: Does README.md explain the auth flow in plain English?

Track dependencies

Tracks can declare dependsOn relationships. conductor run --all resolves them as a DAG — independent tracks run in parallel, dependent tracks wait for their prerequisites to pass before starting. If a prerequisite fails, all downstream tracks are skipped.

conductor add infra --desc="Infrastructure layer"
conductor add api --desc="API layer" --depends="infra"
conductor add frontend --desc="Frontend" --depends="api"

This creates the chain infra → api → frontend. Running conductor run --all will:

1. Run infra first
2. Run api only after infra passes
3. Run frontend only after api passes

conductor doctor catches cycles before you run:

✔  no circular track dependencies

✘  cycle detected: api → frontend → infra → api

AI planning (conductor plan)

conductor plan uses an LLM agent to turn a natural-language goal into a ready-to-run multi-track plan. The agent explores your codebase, designs track ownership, and writes eval:-gated tasks for each track.

# Generate a plan (agent explores your codebase, writes .conductor/plan-draft.md)
conductor plan "add JWT auth with middleware, login endpoint, and rate limiting"

# Show what would change vs current tracks — no filesystem writes
conductor plan diff

# Preview what would be created without applying (alias: --dry-run)
conductor plan apply --dry-run

# Apply interactively — prints the diff and prompts for confirmation
conductor plan apply

# Apply without the interactive prompt (useful in CI)
conductor plan apply --yes

# Run everything
conductor run --all

conductor plan diff compares the generated plan-draft.md against the tracks currently in config.json and prints a colored diff:

+ auth       (new track, 3 tasks)
+ payments   (new track, 2 tasks)
~ frontend   (changed: +1 task, -0 tasks)
  infra      (unchanged)

The generated todo.md files are ready for conductor run — each task has a verifier that evalgate will run after the agent completes its work.

Web dashboard

conductor ui
# → http://localhost:8080

The dashboard is a React app with the Mission Control design system — a blue-black interface built for staying on top of long-running agent runs without losing context.

Design

• Palette — deep blue-black background (#050810), indigo accent (#818cf8), emerald for pass (#34d399), rose for fail (#fb7185), sky-blue for running (#38bdf8)
• Glassmorphic cards — backdrop-filter: blur surfaces with inset highlights and blue-tinted borders
• Animated status dots — running workers pulse continuously; pass/fail states glow in their respective colors
• Typography — Inter for UI chrome, JetBrains Mono for data (IDs, costs, eval commands, logs)
• [conductor] wordmark fixed top-left; the indigo-filled floating pill nav sits independently in the center

Tabs

Tracks has two view modes, toggled via the toolbar:

• Kanban — one column per track, one card per worker. Cards show a status dot, task title, and eval result badge (PASS / FAIL). The column footer shows cumulative token count and estimated USD spend for that track. Click any card to expand the full session log inline. A ⏸ Pause / ▶ Resume button appears in the column header whenever workers are running or the track is paused. If a track has no tasks in todo.md, the Run button is disabled and shows a hint: "Add tasks to todo.md to enable".

• Graph — an orbital topology view. Tracks are arranged in a ring; their workers orbit outward in a 130° arc. Tracks with dependsOn relationships are connected by dashed edges. Scroll to zoom (0.3×–3×), drag to pan, click a track node to open a slide-in detail panel with the full worker list, retry controls, and live-streaming logs. Hover dims non-active tracks. Press Escape or click the background to deselect. View mode is remembered between sessions via localStorage.

  Keyboard shortcuts (graph view):

  • r — run the selected track
  • ↑ / ↓ — cycle focused worker in the detail panel
  • Esc — deselect / close panel
  • ? — toggle shortcut help overlay
  • 1–5 — switch tabs (global)

Workers — flat list of all workers across all tracks, with status, duration, eval badge, and Retry / Logs buttons. A text search box filters by contract title or worker ID; five status pills (all / running / done / failed / pending) narrow the list further. Filter preference is persisted in localStorage.

History — run log across all tracks: date, track, contract title, trigger source, duration, and result (PASS/FAIL). A PASS entry means the eval verifier passed and the git merge committed the work back to main. Export to CSV is available.

Activity — per-track token spend chart. Shows cost accumulation over the session as a canvas bar chart.

Settings — two-column layout: a live tracks table on the left (name, description, agent command, cost per track) and version / defaults / integrations / live session stats on the right. Session stats show total workers, done/failed/running counts, total tokens, and total estimated USD — updated live from SSE.

All updates stream live via SSE — no page refresh needed.

REST API

The web server (conductor ui) exposes a REST API used by the dashboard. You can call it directly:

Budget endpoint

Agent workers can self-report token usage without touching the CLI:

curl -X POST http://localhost:8080/api/tracks/auth/budget \
  -H 'Content-Type: application/json' \
  -d '{ "contractId": "add-jwt", "tokens": 12400, "workerId": "abc123" }'

This triggers a cost SSE event, which immediately updates the cost footer in the dashboard.

Budget guardrails

Each track supports optional per-track budget caps set in config.json (or via conductor add flags):

{
  "tracks": [
    {
      "id": "auth",
      "maxUsd": 2.00,
      "maxTokens": 500000
    }
  ]
}

Or when creating a track:

conductor add auth --desc="Auth layer" --max-usd=2 --max-tokens=500000

When a track's cumulative spend exceeds either cap:

• New workers stop spawning — the orchestrator aborts via AbortSignal; workers already in-flight run to completion, then no new workers start until the budget is cleared or raised.
• PAUSED marker written — a .conductor/tracks/<id>/PAUSED file is written so the paused state survives process restarts and is visible via GET /api/tracks/:id/paused.
• Telegram alert fires — if a Telegram bot is configured (conductor telegram setup), a message is sent immediately with the track name and the breach amount.
• BUDGET badge appears in the UI — the track card in the Kanban view and the Settings tracks table both show a red BUDGET badge so the breach is immediately visible in the dashboard.

Cost is calculated using the input/output token split when available (input: $3/MTok, output: $15/MTok, via evalgate's estimateUsd). If only a total token count is reported (no split), a blended rate of $9/MTok is used.

To resume a budget-paused track after reviewing or adjusting the cap:

# Via CLI (clears PAUSED marker + re-runs pending workers)
curl -X POST http://localhost:8080/api/tracks/auth/resume

# Or via the dashboard — click the green ▶ Resume button in the track column header

Relationship to evalgate

conductor uses evalgate as a library for its worker execution engine. evalgate handles:

• Spawning agents in git worktrees
• Running verifiers after each worker completes
• Persisting swarm state to .evalgate/swarm-state.json
• Emitting events that conductor's SSE server re-broadcasts to the dashboard

You don't need to install or run evalgate separately. It's a bundled dependency.

If you want evalgate's standalone features (pre-commit hooks, MCP server, trigger daemon, ANSI dashboard), install it separately — the two tools are independent and coexist fine in the same repo.

Track CONTEXT.md

Each track gets a CONTEXT.md that describes what the track owns. The conductor prompt builder injects this into each worker agent's system prompt, giving workers scoped context without polluting each other.

# auth

Authentication and session management layer.

## Owned files
- `src/auth/**`
- `src/middleware/auth.ts`

## Constraints
- Never store plaintext credentials
- All tokens must be signed with the app secret
- Session expiry must be <= 24h

Edit this file freely. The next conductor run will pick it up.

Health check (conductor doctor)

conductor doctor audits your project and reports any issues before you run:

conductor doctor

conductor doctor  /your/project

Config
  ✔  config.json exists
  ✔  config.json schema is valid

Tracks  (3 configured)
  ✔  auth/todo.md exists
  ✔  auth: 3 task(s) with eval verifiers
  ✔  payments/todo.md exists
  ⚠  payments: 1 task(s) have no eval verifier: "Update Stripe keys"
  ✔  notifications/todo.md exists
  ✔  notifications: 2 task(s) with eval verifiers
  ✔  no circular track dependencies

Git worktrees
  ✔  no stale worktrees detected

Dependencies
  ✔  evalgate 2.1.0 installed (required: ^2.1.0)
  ✔  agent "claude" found on PATH

All checks passed.

Checks performed:

1. .conductor/config.json exists and passes schema validation
2. Each track has a todo.md file
3. Each task has an eval: verifier (warns if missing)
4. No circular dependsOn references between tracks
5. No stale git worktrees from previous crashed runs
6. evalgate version satisfies the declared dependency range
7. Agent commands (claude, or custom agentCmd) are on $PATH
8. Any schedule cron expressions are valid

Programmatic API

conductor-agents can be used as a library in addition to the CLI:

npm install conductor-agents

import { runTrack, listTracks, loadConfig, validateConfig } from "conductor-agents";

// Load and validate config
const config = loadConfig("/your/project");

// Run a track's swarm
const result = await runTrack("auth", { cwd: "/your/project", concurrency: 2 });

// Check all tracks
const tracks = await listTracks("/your/project");

// Start the HTTP server programmatically
import { startServer } from "conductor-agents";
const server = await startServer({ port: 8080, cwd: "/your/project" });
// ... later:
server.close();

Full API surface:

// Config
loadConfig, saveConfig, validateConfig, configDir, configPath, trackDir, trackTodoPath, trackContextPath
// Tracks
createTrack, deleteTrack, getTrack, listTracks, initConductor
// Orchestration
runTrack, runAll, retryTrackWorker, getTrackState, getTrackCost, getTrackSpend, detectCycle, pauseTrack, resumeTrack, isPaused
// Server
startServer
// MCP
startMcpServer
// Planner
generatePlan, applyPlan, parsePlanDraft, buildContextSnapshot
// Types
ConductorConfig, Track, TrackStatus, TrackCostSummary, TelegramBotConfig

Docker

docker pull ghcr.io/jorgejac1/conductor-agents:latest

Or build locally:

docker build -t conductor-agents .

Mount your project directory and run any conductor command:

# Health check
docker run --rm -v $(pwd):/app conductor-agents doctor /app

# Run a track (requires git + agent command inside container or mounted)
docker run --rm -v $(pwd):/app conductor-agents run auth /app

The image is based on node:22-slim with git installed (required for worktrees).

Roadmap

Contributing

git clone https://github.com/jorgejac1/conductor-agents
cd conductor
npm install
npm run build
npm test

PRs welcome. Run npm run lint:fix before committing.

License

MIT