conductor

conductor

Verified tool calls for Claude Code: an MCP server (installable as a plugin) whose 23 tools check their own output in code before you get it.

A model asked to "extract the email" or "redact the phone numbers" is usually right, and nothing tells you when it isn't. conductor puts each job behind a contract: an input schema, an output schema and a mandatory verifier. Deterministic jobs (slugs, base64, URL extraction) run as plain code and never touch a model. Judgment jobs (summaries, PII redaction) run as hermetic claude -p calls, and an answer that fails its verifier is retried with the failure as feedback, handed to a fallback, or returned as a failure; it is never silently passed through.

The skeleton (validate -> execute -> verify -> retry -> fallback -> log) is real code that cannot be skipped; the model is quarantined to the judgment-shaped holes.

Quick start

You need Claude Code installed and logged in, and Node.js 20 or newer on your PATH (the plugin starts the server with node).

claude plugin marketplace add fainir/conductor

claude plugin install conductor@conductor

Restart Claude Code (or run /reload-plugins in a running session). Inside a session the same steps are /plugin marketplace add fainir/conductor and /plugin install conductor@conductor. Check that the server is up:

$ claude mcp list

plugin:conductor:conductor: node /Users/you/.claude/plugins/cache/conductor/conductor/0.4.1/dist/conductor-mcp.cjs - ✓ Connected

Then ask for the job in plain words, for example "redact the PII in this ticket with conductor". The tools show up as mcp__plugin_conductor_conductor__ .

Update with claude plugin marketplace update conductor && claude plugin update conductor@conductor, remove with claude plugin uninstall conductor@conductor.

Without the plugin system. dist/conductor-mcp.cjs is a committed, self-contained bundle, so a clone needs no install or build step:

git clone https://github.com/fainir/conductor

claude mcp add conductor -s user -- node "$PWD/conductor/dist/conductor-mcp.cjs"

Other MCP clients can run npx -y @fainir/conductor, which serves MCP over stdio. The unrelated conductor-mcp package on npm belongs to someone else.

Usage

Every tool returns the same envelope. Real output from the bundle for base64_encode with {"text": "hello"}:

{ "ok": true, "output": { "encoded": "aGVsbG8=" }, "via": "base64_encode", "attempts": 1, "verdict": { "ok": true, "score": 1 } }

via names the rung that produced the answer (the tool itself, a declared fallback, or freeform for plain Claude), and attempts counts tries on that rung. A failure sets ok: false and the tool result's isError, and the verdict says why, so the calling model can fix its call:

{ "ok": false, "via": "redact_pii", "attempts": 0,

"verdict": { "ok": false, "score": 0, "feedback": "invalid input: input: missing required property 'text'; input: unexpected property 'txt' (allowed: text)" } }

From a clone you can drive the same loop with the CLI (npm ci first). Pure tools answer instantly and cost nothing:

$ npx tsx src/cli.ts slugify '{"text":"Hello, World!"}'

{ "ok": true, "output": { "slug": "hello-world" }, "command": "slugify", "attempts": 1, "verdict": { "ok": true, "score": 1 }, "costUsd": 0 }

$ npx tsx src/cli.ts normalize_phone '{"phone":"call me"}' { "ok": false, "command": "normalize_phone", "attempts": 1, "verdict": { "ok": false, "score": 0, "feedback": "shape: normalized must match /^\\+?\\d{6,15}$/ (an optional leading '+' followed by 6-15 digits)" }, "costUsd": 0 }

The CLI exits 1 when the result fails verification. Model-backed tools work the same way (npx tsx src/cli.ts extract_contact '{"text":"Call Sam at sam@acme.io"}') and spend a claude -p call per attempt. npx tsx src/cli.ts with no arguments lists the commands, and npx tsx src/cli.ts route "make a url slug" '{"text":"Hello World"}' lets a model pick the command.

Tools

Pure tools (code only, no model call)

Model-backed tools (hermetic claude -p call)

Inputs ending in ? are optional. The first three columns come from the command manifests (npm test fails if they drift); the full JSON Schemas are what the MCP server advertises.

How it works

input -> inputSchema check -> run the command -> verify -> ok? -> result

^ | no +-- retry with the verifier's feedback (model-backed, up to maxAttempts) | still no declared fallbacks -> freeform (plain Claude, same schema, same verifier)

• Contracts with mandatory verifiers. Each command is commands/ /index.ts: a manifest (input and output JSON Schema, determinism, prompts, fallbacks) plus a verify() export. A command without a verifier cannot be registered (src/library.ts, src/registry.ts). Mechanical checks come first (schema, regex, recompute, grounding); llmJudge in src/verify.ts exists for criteria no code can express.
• Precondition gate. Input that breaks the command's inputSchema is rejected before anything runs, with a message that names the problem.
• Determinism gradient. pure commands are deterministic code: run once, cached, free, and never sent to a model. stochastic commands are run by the model and retried with feedback. effectful is reserved for commands that will need a human gate.
• Fallback to freeform. Every model-backed ladder ends at plain Claude, held to the same output schema and verifier, so the conductor never does worse than a raw call, only better when a verified command applies.
• Hermetic calls. Every model call (src/cc.ts) replaces the system prompt (--system-prompt), loads no settings (--setting-sources ""), enables no tools (--tools ""), saves no session, and constrains the answer with --json-schema. This matters: a naive call once returned the operator's own email instead of the one in the input, because ambient context (global CLAUDE.md, identity, hooks) leaked in.
• Composition. runPipeline (src/pipeline.ts) chains commands; each step is verified before the next runs, so errors cannot silently compound.
• Telemetry and routing. Every attempt is a JSONL line. npm run scores prints per-command reliability from the CLI and eval logs, and route() (src/router.ts) shows those rates to a small model that must pick from an enum of command names.

Configuration

Model-backed calls use whatever account the claude CLI is logged into.

Results (measured by the author)

Evals compare a single naive claude -p call with the conductor on the same inputs:

• Single-shot extraction (eval/run-eval.ts): baseline 100% vs conductor 100%. On easy single-shot tasks a frontier model is already reliable, so there is no gap to close.
• Composition (eval/contact-card.ts, extract_contact -> normalize_pho