io.github.dcondrey/misterdev

misterdev

Autonomous LLM build orchestrator: plans a goal into tasks, edits code with anchored SEARCH/REPLACE, and verifies every change through build/test/lint/typecheck gates before reporting done. Runs as a CLI or MCP server.

Install · What it does · CLI · Extending · Configuration · Development · License

Point misterdev at a repository and a goal. It reads the codebase as a symbol graph, decomposes the goal into concrete tasks, and works each one in a try-edit-verify loop: it emits an anchored SEARCH/REPLACE edit, applies it against the file on disk, and runs the change through a sequence of correctness gates — build, tests, lint, typecheck, and any optional gates you enable. A gate that fails RED blocks the change; a gate that has nothing to check SKIPs and never blocks. When a change regresses the suite, misterdev reverts it through git. Nothing merges unless it stays green.

$ misterdev build . "add rate limiting to the public API"

  planning   goal → 3 tasks  (model: anthropic/claude-sonnet-4-6, budget $100.00)
  task 1/3   middleware: token-bucket limiter          api/limiter.py
    edit     1 hunk applied · syntax ok
    gates    build GREEN · tests GREEN (142 passed) · lint GREEN · typecheck GREEN
  task 2/3   wire limiter into request pipeline         api/app.py
    edit     2 hunks applied
    gates    build GREEN · tests RED (1 failed) → rolling back, regenerating
    edit     2 hunks applied (attempt 2)
    gates    build GREEN · tests GREEN (145 passed) · lint GREEN · typecheck GREEN
  task 3/3   docs + config surface                      README.md, config.py
    gates    all GREEN

  done       3/3 tasks · 145 tests green · $0.38 over 11 calls

Because misterdev only trusts its gates, the loop is honest: "the model said it's done" is never the finish line — the build, the tests, and the diff are.

Install

pip install misterdev
# or
uv pip install misterdev

Python 3.10 – 3.13. Optional extras add capability without bloating the core install:

pip install 'misterdev[local-embeddings]'   # offline semantic context ranking (fastembed, no API key)
pip install 'misterdev[lsp]'                 # LSP semantic-diagnostics gate
pip install 'misterdev[web]'                 # headless-browser web verification gate (+ playwright install chromium)
pip install 'misterdev[mcp]'                 # Model Context Protocol tool-host substrate

Extras are all opt-in and timeout-bounded. When an extra's runtime dependency is absent, the gate it powers SKIPs rather than failing.

What it does

Autonomous build loop

Give misterdev a goal and it drives the whole cycle: analyze the project, plan tasks, edit, and validate — repeating until the goal is met or the budget is spent. Edits are anchored SEARCH/REPLACE hunks: the model emits only the changed regions, which are applied against the on-disk file, so a 5,000-line module is edited without reprinting it and without hitting the output-token ceiling. Matching tries exact first, then tolerates whitespace and indentation drift, always requiring a single unique anchor so a partial file is never written.

Polyglot symbol-graph context

A tree-sitter symbol graph gives misterdev structural understanding of Python, Rust, TypeScript/JavaScript, Go, Java, C/C++, C#, Swift, and Kotlin. Per-file outlines plus a whole-project structural map feed planning and editing, and large files are sent as a symbol outline plus verbatim windows of the task-relevant symbols — so context and cost scale with the edit, not with the file.

Correctness gates

Every change runs through an ordered gate sequence: build → lint → tests → typecheck, with optional gates layered on top — an adversarial critic (an independent second model that reviews each diff before it is applied), goal-check, claim-verifier, mutation scoring, runtime-smoke, web, and vision verification. A gate that fails RED blocks the change; a gate with nothing to check SKIPs and never blocks. Regressions are reverted via git, so a working tree only ever moves forward.

Dynamic model selection

misterdev keeps a per-model performance ledger and pairs it with a cost-aware selector that picks for quality-per-dollar across the full breadth of OpenRouter — routing each task up a capability ladder (harvested free / cheap → a strong mid-tier → a frontier tier) and escalating to a stronger model only when a cheaper one can't clear the gates. The strongest tier is reserved for the final attempt, so frontier spend is the rare safety net, not the default; a hard task that a mid model stalls on is finished by a frontier model, while easy tasks resolve on free/cheap ones. Quality never drops because a weak model that writes bad code fails the gate and the policy climbs. It runs against OpenRouter or Anthropic with automatic failover, caches responses to avoid paying twice, and token budgeting keeps spend inside the ceiling you set.

Parallel worktrees

Disjoint tasks run concurrently, each in its own isolated git worktree, so independent work doesn't contend for the tree. An integration gate re-checks each wave against the full suite and reverts any task that regresses it — parallelism without cross-contamination.

Self-improving

misterdev keeps a durable, fingerprinted stream of its own real failures and runs an AlphaEvolve-style keep-if-better loop over its own source: it attributes what breaks, classifies why (harness artifact vs observation gap vs capability), proposes a targeted structural self-edit, and promotes it only when it beats the champion on a held-out task set it never optimized against — with zero regressions. A reward-hacking guardrail walls off the tests and benchmark. The result is a loop that removes whole failure classes over time without overfitting to any one benchmark. See docs/path-to-100.md.

Run it with misterdev evolve --benchmark <polyglot-benchmark checkout> --workdir <scratch dir> (dry-run by default; add --live to actually apply/gate/promote, --from-failures to target the real-build failure stream instead of the benchmark's worst niche). evolution.benchmark_dir/evolution.noise_band in project.yaml set the defaults so a caller can omit the matching flags; both are opt-in and unset by default. An evolve_async MCP tool runs the same pass in the background (poll with job_status). A nightly --scheduled --live --from-failures pass also runs via .github/workflows/evolve.yml once the repo secret OPENROUTER_API_KEY is configured — gated by the same exclusive lock + circuit breaker, so an overlapping or repeatedly-failing trigger is a clean no-op.

On the correctness side, misterdev works reproduction-first: for an issue-driven task it synthesizes a failing test from the acceptance criteria, validates that the test actually fails on the clean tree (a test that reproduces nothing is discarded rather than trusted), then drives the fix to turn it green — so the model edits toward a concrete, verified target instead of a description.

Two-timescale evolution (built; opt-in via orchestrator.runtime_tooling; see docs/two-timescale-evolution.md) takes the self-improvement further than a memoryless runtime agent can. At runtime, the model may author a small task-specific helper tool that runs sandboxed (a hardened, network-less container — untrusted code never touches the host or the repo, and with no container engine the capability degrades off); its output feeds the edit. Every invented tool is then captured with the task's outcome into a tool corpus — a free byproduct of normal runs — and a deliberate promotion pass admits the tools whose success generalizes on a held-out task split (baseline drawn from the reproduction corpus) into a persistent, best-per-capability tool library that future runs start from. Fast loop invents; slow loop keeps only the winners; the same held-out gate that guards scaffold self-edits keeps the library general rather than benchmark-overfit. Capability compounds across runs instead of being reinvented each task — the memory the current top open-source scaffolds lack. Run the promotion pass with python -m misterdev.core.evolution.tool_promotion <project>.

Extensibility

Tools, gates, and targets self-register through Python entry points. pip install misterdev-plugin-x adds a capability with zero edits to the core — misterdev discovers the entry point at runtime and wires it in. A working example lives at examples/misterdev-plugin-hello. See Extending misterdev.

Agentic MCP

misterdev can connect to Model Context Protocol servers and let the model call their discovered tools mid-build — bounded, opt-in, and constrained by a tool allowlist. Transports include stdio and remote streamable-http with auth, so you can point it at a hosted MCP gateway like Glama and give the build access to a whole catalog of tools without running any of them locally.

Benchmarks

Gate-verified pass@1 on Aider's polyglot benchmark (Exercism exercises with hidden test suites), anthropic/claude-sonnet-4-6:

A continuous stress run has solved 20/20 across the three languages with zero failures — including the exercises usually cited as hard (bowling, forth, arbitrary-precision decimal). Every solve is judged by the exercise's own hidden tests, not the model's say-so. Full numbers, methodology, and how to reproduce: docs/benchmark-results.md. Test suite: 1,941 passing — docs/TESTING.md.

CLI reference

Don't want to remember flags? Just describe what you want — no project setup or devplan required. misterdev routes it with zero friction:

$ misterdev "add rate limiting to the public API"
  ⠸ Building…

Action words (add, fix, implement, write, create, …) go straight to build — no LLM routing call, no confirmation prompt, no ceremony. Query and management words (list, status, what, how, check, run, …) are mapped with a model call, shown as a preview, and ask before anything mutating:

$ misterdev "check what's broken and fix it cheaply, run in parallel"
  → I'll run: misterdev build . fix broken tests --budget 5 --parallel
    proceed? [Y/n]

The flag-based commands below still work for scripts and power users. The misterdev command drives everything:

Plain misterdev with no subcommand launches interactive planning.

Drive it from an AI client (MCP server)

misterdev also ships as an MCP server (misterdev-mcp), so you can drive it in plain English from Claude Desktop, Claude Code, Cursor, or any MCP client — no flags to remember. The client just calls a tool (build, scan, status, list_projects, run); the entire orchestration runs inside misterdev's own process with its own model and context budget, and only a short summary returns to the client — your codebase never enters the client's context window.

// Claude Desktop config (claude_desktop_config.json)
{
  "mcpServers": {
    "misterdev": {
      "command": "misterdev-mcp",
      "env": { "OPENROUTER_API_KEY": "sk-..." }
    }
  }
}

Then just ask: "Have misterdev add rate limiting to the API, keep it under $5." Mutating tools (build, run) refuse a dirty working tree and carry a conservative default budget.

Claude Code integration. The build tool accepts a spec_text parameter. Pass a complete spec written by Claude and misterdev skips its own analysis and spec-generation phases, going straight to decompose → execute → verify using your codebase's own gate suite. Claude handles the design; misterdev handles the execution, correctness gates, and rollback:

# In Claude Code / MCP client
misterdev.build("/path/to/repo", spec_text="""
Feature: add a token-bucket rate limiter to /api/v1/*
...full spec...
""")

Requires the mcp extra: pip install 'misterdev[mcp]'.

Extending misterdev

A plugin is an ordinary Python package that declares entry points in the misterdev.* groups. Install it, and misterdev picks it up — no core edits.

A tool is a class; a gate is a callable returning a GateOutcome:

# misterdev_plugin_hello.py
from misterdev.core.execution.outcomes import GateOutcome, GREEN, RED


class HelloTool:
    gather_safe = True  # opt into the agentic gathering loop
    gather_description = "Return a friendly greeting for a name."

    def __init__(self, config: dict):
        self.name = config.get("name", "hello")

    def execute(self, project, name: str = "world", **_ignored):
        return True, f"Hello, {name}!"


def no_shouting_gate(ctx) -> GateOutcome:
    build = (ctx.commands or {}).get("build_command") or ""
    if build and build.isupper():
        return GateOutcome(RED, "build_command is ALL CAPS; please calm down")
    return GateOutcome(GREEN)

# pyproject.toml — the entry points are the whole contract
[project.entry-points."misterdev.tools"]
hello = "misterdev_plugin_hello:HelloTool"

[project.entry-points."misterdev.gates"]
no_shouting = "misterdev_plugin_hello:no_shouting_gate"

Targets register the same way through the misterdev.targets group. The full, runnable example — tool, gate, pyproject.toml, and notes — is at examples/misterdev-plugin-hello.

Configuration

A project.yaml is created automatically when you first run misterdev in a directory — no setup required to get started. Drop a custom one in the repo root to specify build/test/lint commands, model, budget, and gates.

name: "My App"
language: "python"
build_command: "python -m compileall -q ."
test_command: "pytest -q"
lint_command: "ruff check ."
llm:
  provider: "openrouter"            # openrouter | anthropic
  model: "anthropic/claude-sonnet-4-6"
  api_key_env_var: "OPENROUTER_API_KEY"

Key knobs:

• Model & budget — llm.model, provider/failover, and the run's dollar ceiling (also --budget).
• Gates — optional gates (adversarial critic, mutation, runtime-smoke, web, vision, goal-check) are off by default and enabled under the orchestrator.* keys.
• MCP — declare servers under mcp.servers and enable tool use with orchestrator.mcp_enabled / orchestrator.mcp_tool_use; point at a remote gateway for hosted tool catalogs.
• Targets — a targets: block gives a polyglot monorepo per-language build/test/lint, routed per task.

Guides: Getting started · Configuration · Plugins · MCP. project.yaml.example documents every configuration key.

Requirements

• Python 3.10 – 3.13
• git (branch-per-task, worktrees, and rollback all run through it)
• An API key for OpenRouter or Anthropic
• Optional per-gate toolchains — a Playwright browser for the web gate, a language server for the LSP gate, an MCP SDK for the tool-host substrate (all installed via the matching extra)

Development

git clone https://github.com/dcondrey/misterdev
cd misterdev
uv sync
uv run ruff check .
uv run pytest -q

Contributions are welcome — see CONTRIBUTING.md, and open an issue or a pull request on GitHub.

License

misterdev is dual-licensed:

• AGPL-3.0-or-later — free for open-source use under the terms of the GNU Affero General Public License.
• Commercial license — for use in a closed-source or proprietary product without AGPL obligations.

Choose the one that fits your project.

Built by David Condrey · github.com/dcondrey/misterdev
_{The static mark lives at assets/logo.svg.}