Leopold

Brief it like a teammate. It conducts Claude Code — or Codex — in your seat.

Leopold is an autonomous orchestration harness for Claude Code and Codex CLI. You debate the work with it — goals, constraints, taste, what "done" means — and that becomes a durable brief. Then it takes the seat and drives your agent continuously, deciding the way you would instead of stopping at every fork, until the plan is done or a stop condition fires — with your git locked the whole time.

It is the same product on either agent: the same skills, the same two hooks (unmodified scripts — Codex reimplemented Claude Code's hook contract nearly field for field), the same four extensions, the same dashboard, the same driver.

The name nods to Bugs Bunny: in Long-Haired Hare (1949) he seizes the podium as the conductor Leopold and runs the orchestra with a wave of the baton. You are the composer, Leopold the conductor, Claude Code the orchestra.

Status: alpha. The in-session engine (skills + hooks) works today; the SDK driver (packages/driver/) typechecks against the Agent SDK. See Roadmap.

Quickstart

# from npm — no clone, no make. `leopold up` installs the harness + sets up the project.
npm i -g leopold-driver && leopold up

# or the one-line installer
curl -fsSL https://raw.githubusercontent.com/Jonhvmp/leopold/main/install.sh | bash

Either way, the installer finds whichever harness you have and wires it: skills + hooks into
~/.claude/ (merged into settings.json), and/or into ~/.codex/ (merged into
config.toml). Pick one explicitly with --harness claude|codex|all. The extensions
(serena, gstack, ovmem, enhance) install and report per harness, and leopold watch
reads a Codex run's real tokens, cost and context — a Codex-only machine gets the whole
product with nothing pointing at a Claude path. See
Claude Code and Codex.

With the npm package, the bundled leopold CLI runs the whole toolchain without the
repo:

leopold up                   # install + project setup in one (then /leopold-up in a session)
leopold menu                 # toolchain manager (serena / gstack / ovmem / enhance)
leopold enhance toggle       # global prompt enhancer: Haiku interprets weak prompts (your account)
leopold watch                # live dashboard at http://127.0.0.1:4179 (incl. workflow phase tree)
leopold harness              # which harnesses are here, and what each one can do
leopold run --parallel 3     # conduct the run, independent items in parallel
leopold run --provider codex # conduct the same brief on Codex instead
leopold workflow             # compile the brief into a dynamic workflow (--run: headless, exp.)
leopold insights             # summarize a run (effort mix, review pass-rate, spend)
leopold doctor               # health check

# clone (transparent)
git clone https://github.com/Jonhvmp/leopold.git && cd leopold && ./install.sh
# as a Claude Code plugin (auto-wires skills + hooks)
claude plugin marketplace add Jonhvmp/leopold && claude plugin install leopold@leopold
# Codex only (skills + the git lock and continuity hooks in config.toml)
./install.sh --harness codex

Then, in any project:

/leopold-brief    # debate the mission, write the brief (plan by tournament on big missions)
/leopold-run      # hand over the seat (single-context loop)
/leopold-workflow # compile the brief into a dynamic workflow and run it
/leopold-learn    # mine your decisions + sessions → proposed charter amendments
/leopold-enhance  # global prompt enhancer: status, on/off, preview, learn
/leopold-triage   # triage a backlog (quarantined classifiers, dedupe, fix plans)
/leopold-watch    # live web dashboard: cost meters, events, decisions, Stop
/leopold-status   # see where it is (terminal)
/leopold-stop     # take the seat back

The cast at the top is a scripted walkthrough (regenerate it).
For a full reproducible run — a real brief and the DECISIONS.md it produced — see
examples/add-json-output/.

How it works

Phase 1 — Brief (/leopold-brief). A structured debate, not a form. Leopold pushes back and writes four durable artifacts: MISSION.md (what + definition of done), CHARTER.md (your priorities, taste, hard never/always rules — the part that "becomes you"), GUARDRAILS.md (autonomous vs gated, stop conditions, kill switch), and PLAN.md (the backlog). The run's quality is capped by the brief's, so this phase matters.

Phase 2 — Run (/leopold-run). Leopold loops: pick the next PLAN.md item → do the work, reaching for the right gstack skill → at a fork, consult CHARTER.md; if the call is reversible and the charter is clear, decide, log it to DECISIONS.md, and keep going → mark it done, pick the next. A Stop hook re-injects "continue" while work remains; a PreToolUse guard keeps git commit/push locked. Everything it decided for you is in DECISIONS.md to review.

Phase 2, the workflow way (/leopold-workflow). Same brief, stronger engine. Leopold compiles the brief into a dynamic workflow — a JavaScript harness Claude Code's runtime runs in the background. The plan lives in code instead of one growing context window, so the run doesn't drift into agentic laziness, self-preferential bias, or goal drift on a long plan. PLAN.md becomes dependency-ordered waves; each item gets an independent adversarial reviewer (a panel with a security lens on critical items) that did not write the code it judges. The run is resumable and streams a live phase tree into /workflows (and into leopold watch). Git is locked for free — a workflow can't commit; it stages, you commit. The compiler is also a first-class driver command: leopold-driver workflow emits the script + args deterministically (CI-checkable), and --run executes it headlessly through an experimental in-driver runtime. Use /leopold-run for a short or interactive plan; reach for /leopold-workflow when the plan is large or parallelizable. See the Dynamic Workflows concept page.

Quality & orchestration

Leopold extracts the most from Claude Code's native power, in one command. See Quality & Orchestration.

• A panel of skeptics on every item. Before an item closes, a diverse-lens review panel passes over its diff — correctness always, +security on sensitive diffs, +does-it-actually-work on critical items. Each panelist is an independent session that did not write the code; blocking findings are unioned and go back to the worker until the panel is clean. Diversity beats redundancy: different lenses catch failure modes identical reviewers structurally miss. Give an item @scenario acceptance lines and a conformance lens verifies the diff satisfies every one before it closes — backward-compatible, off when no scenarios are declared.
• Root-cause panel when an item is stuck. A failed item isn't just retried: three investigators form hypotheses over disjoint evidence (the diff, the verification output, the item's assumptions vs the codebase), refuters try to kill each one, and the surviving theory becomes a concrete lead for the next attempt — the structural fix for an agent doubling down on its own wrong theory. In a worktree-isolated run a literal reset also throws out the failed diff and restarts the retry from the pre-attempt snapshot, and --best-of-k N settles a critical item by a tournament of N independent attempts, applying the winner.
• Effort by risk — keywords or research. Each item is classified and the worker's reasoning effort is set automatically — low for a typo, max for a migration or payment change. --smart-routing upgrades this: a short read-only session researches the item's real blast radius (how many callers, what it touches) before routing; it always falls back to the deterministic classifier and never lowers a critical floor. Add --slice-scope and that researched file set is handed to the worker as an explicit "start with these files" scope.
• A charter that learns you (/leopold-learn). Your recorded behavior beats your self-description: independent miners sweep the decision log, your session corrections, and git history for recurring judgment calls; a skeptic kills the weak candidates; the survivors become proposed charter amendments you review. Each pass makes the next run decide more like you. The SDK driver can close this loop automatically — learn_on_finish: on (or --learn-on-finish) mines each clean run into CHARTER-amendments.md the moment it finishes, without ever editing the charter itself.
• A prompt enhancer that reads your shorthand (enhance). Everyday prompts are thin by habit ("fix login"). One global UserPromptSubmit hook (on both harnesses) scores each prompt; genuinely weak ones get a structured interpretation from Haiku on your own account — charter-aware, conversation-aware — injected next to the raw prompt, which always wins on conflict. Strong prompts (anything anchored to a path or symbol) never pay the latency; failures fail open. Off by default: leopold menu → enhance → Toggle. /leopold-enhance learn mines the local ledger for interpretations you corrected and proposes prompt-profile rules — you review, it never self-edits. Docs.
• Parallel items. leopold-driver run --parallel N runs independent plan items at once, each in its own worktree, replaying each diff onto the main tree (staged, never committed). Declare order with - [ ] (after: 2) ….
• One-command setup. leopold up + /leopold-up wire the things people skip — CLAUDE.md (/init), an app run-skill (/run-skill-generator), a permissions allowlist, MCP — so a project starts at full power.
• Insights. leopold-driver insights summarizes a run: effort mix, review pass-rate, decisions, escalations, real spend.

The Canvas

Leopold's plan is a graph, not a chat thread — so it renders as one. The Canvas tab in leopold watch is a live, zero-dependency DAG of the run (plan items, workflow phases/agents, forks, adversarial-verify, tasks — with dependency edges), laid out by a hand-rolled layered layout. No framework, no bundler, no web fonts; it binds to loopback and runs fully offline. See The Canvas.

• See the run as a graph. Pan, zoom, drag-to-pin, fit-to-view. Click any node to inspect it — model, tokens, a per-node cost estimate, prompt/result previews, and a plan item's DECISIONS.md rationale. Verify agents link to the exact node they reviewed wherever Leopold's own scripts label them.
• Steer from the canvas. Redirect, inject, kill, or re-run a node. A live /leopold-run drains the command from .leopold/commands.jsonl at the next turn boundary; a non-preemptible workflow node's steer becomes an honest directive for the next resume. Git stays locked — a steer command can never unlock or commit, proven by a red-team test on both the dashboard and the driver.
• Deliberately narrow. Not a general knowledge-work assistant: no deck/sheet generation, no connectors marketplace, no enterprise SIEM, no real-time multi-user collab, no task board. A graph-native, open, self-hostable view-and-steer surface for a run — nothing it shows is a claim the tests don't back.

Safety — autonomy you can trust

Because Leopold sells autonomy, guardrails are the product, not an afterthought.

• Git stays locked. git commit and git push (force-push always) are blocked while autonomous — regardless of permission mode. That's the whole lock: the run stages and reports, you commit and push. You opt in explicitly, per run (ALLOW_GIT / ALLOW_PUSH), or they never run. Everything else — edits, builds, tests, rm, refactors, subagents — is the run's own call; isolate with --worktree if you want a filesystem boundary.
• Red-teamed. The guard ships a bypass-attempt test suite (make test-guard), plus unit tests for the TS driver guard, covering evasion tricks like git -c user.name=x commit, /usr/bin/git push, env git commit, and whitespace/tab splitting. Think you can slip a commit or push past it? Open an issue — break it.
• Cost-capped. A long autonomous run runs up a bill because the main session re-bills its growing context every turn. Leopold's dependable ceiling is the --budget <usd> hard-stop (stops the moment real spend crosses it), backed by a bounded, resumable loop (max_iterations, resume fresh from the brief). The protocol keeps the orchestrator lean — bulk-output work is delegated to subagents that write to files, so output never piles up in the main context.
• Fails closed. A malformed run-state file blocks loudly; it never silently lets autonomy through.
• Kill switch + audit. /leopold-stop (or touch .leopold/STOP) halts at the next turn boundary; every autonomous decision is logged with its reasoning.

Leopold never weakens the harness's own permissions — it adds a second lock on top. The lock is the same script on Claude Code and on Codex, because Codex reimplemented Claude Code's hook contract: same event names, same payload keys, same deny reply. Details: docs/guardrails.md.

What is a harness?

Agent = Model + Harness — everything around the model: orchestration, memory, guardrails, observability. Claude Code and Codex are both great harnesses for one interactive turn. Leopold adds the layer they lack for unattended work: a decider (your charter, so it chooses instead of asking), continuity (a stop hook, so a finished turn rolls into the next item), behind guardrails (the gate above). It runs on either — the brief in .leopold/ is plain markdown, and both hooks are the same scripts on both. More in What is a harness and Claude Code and Codex.

gstack + the toolchain manager

gstack is a battle-tested suite of Claude Code skills (/spec, /code-review, /qa, /ship, /investigate, …). Leopold doesn't replace it — it conducts it: gstack skills auto-switch to "pick the recommended option and report" inside an orchestrator, so the whole toolchain runs autonomously. Optional, but it's where planning shines (/autoplan, /plan-*-review).

A small interactive menu installs and manages the toolchain + companion extensions:

make menu     # or: bash ~/.claude/leopold/scripts/leopold-menu.sh

Each component lives under extensions/ (an extension.json + a manage.sh). Built in:

• serena (mandatory) — LSP code intelligence over MCP: symbol-level retrieval + editing instead of grep/whole-file reads. Set up automatically by the installer (make serena-install); it's the biggest lever for both code quality and lean context (fewer tokens per op).
• gstack — the planning/QA skill suite Leopold conducts.
• ovmem — autonomous RAG long-term memory (OpenViking + 4 hooks; OpenAI or AWS Bedrock; runs entirely on 127.0.0.1).

Every one of them installs, reports status and runs its doctor per harness — claude mcp add + settings.json on Claude Code, codex mcp add + config.toml on Codex, written by one shared helper so the two can't drift. A two-harness box never sees one harness's state passed off as both.

Walkthrough: Toolchain Manager.

Architecture at a glance

Full design in docs/architecture.md.

Roadmap

• In-session engine: skills + Stop/PreToolUse hooks
• leopold doctor — verify install, hooks, gstack wiring
• Guard red-team suite — bypass attempts blocked in CI
• SDK driver — external orchestrator on the Claude Agent SDK, shipped on npm as leopold-driver
• Multi-worker fan-out (run --parallel N, one worktree per item) + leopold watch web dashboard (cost meters, decision log, workflow phase tree)
• Dynamic-workflow engine: /leopold-workflow, leopold workflow (compiler as tested code), /leopold-learn, /leopold-triage, plan-by-tournament
• Quality panels: diverse-lens review + conformance scenarios, root-cause hypotheses + literal reset, smart routing + slice scope, best-of-k tournaments; 161 driver tests + CLI smoke in CI (Ubuntu + macOS)
• Harness-universal: skills, both hooks, all four extensions, the dashboard and the driver on Claude Code and Codex CLI, with a hermetic end-to-end Codex install test in CI
• Headless workflow --run exercised end to end; sandboxed workers (E2B/Daytona) — see the full roadmap

Documentation

Full docs (Material + Mermaid): https://jonhvmp.github.io/leopold/ — Quickstart · What is a harness · Architecture · Leopold vs Ralph

License

MIT. See LICENSE.