misterdev 0.2.0

An autonomous, extensible LLM build orchestrator that plans, edits, and verifies code across languages.

misterdev

An autonomous LLM build orchestrator that plans a goal into tasks, edits your code with surgical precision, and verifies every change through correctness gates before it ever reports done.

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, harvests free models where they hold up, and caches responses to avoid paying twice. It runs against OpenRouter or Anthropic with automatic failover, 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.

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.

CLI reference

Don't want to remember flags? If the first argument isn't a subcommand, misterdev treats the whole line as plain English, maps it to an action with its own model, shows you a preview, and asks before anything mutating:

$ misterdev "fix the failing tests but keep it cheap, and run stuff in parallel"
  → I'll run: misterdev build . fix the failing tests --budget 5 --parallel
    proceed? [Y/n]

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

Command	What it does
misterdev scan <dir>	Discover projects under a directory and register them.
misterdev list	List all registered projects.
misterdev status [path]	Show a project's tasks and their state.
misterdev report [path]	Summarize the latest build's cost/tokens, per-model ledger performance, and the audit trail. Read-only — nothing is re-run.
misterdev run [path]	Run pending (or a specific --task) tasks for a project. --dry-run, --force, --status.
misterdev plan [path]	Analyze the project, recommend work, and compose a plan interactively. --budget, --no-rollback.
misterdev build [path] [prompt]	The autonomous build/debug/complete workflow. See flags below.

Plain misterdev with no subcommand launches interactive planning.

misterdev build flags

Flag	Effect
--budget <float>	Max dollar budget for the run (default 100).
--commit	Commit after each completed task.
--parallel	Execute independent tasks concurrently in isolated worktrees.
--dry-run	Plan only; show tasks without executing.
--interactive, -i	Wait for confirmation between tasks.
--no-verify	Skip the final validation phase.
--no-suggest	Skip the suggest scan.
--no-rollback	Disable auto-bisect/revert of a regressing task.
--focus <area>	Restrict work to a specific area.
--allow-dirty	Allow building over uncommitted changes.
--max-tasks <n>	Cap the tasks this run will plan/execute (bounds cost).

The prompt is free text or a mode word — debug, complete, review, or new <description>.

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. 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

Drop a project.yaml in the repo root. A minimal config names the language and the build/test/lint commands; everything else has a sensible default.

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.}