# misterdev [Health: Active]
**Category:** 💻 Developer Tools
**Repository:** https://github.com/dcondrey/misterdev
**GitHub Stars:** 3
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/misterdev
## Description
Autonomous LLM build orchestrator that plans, edits, and verifies code across languages.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):
```json
"mcpServers": {
"misterdev": {
"command": "uvx",
"args": ["misterdev"]
}
}
```
## Documentation & README
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.
[](https://github.com/dcondrey/misterdev/actions/workflows/ci.yml) [](https://www.bestpractices.dev/projects/14406) [](https://github.com/dcondrey/misterdev/blob/main/LICENSE) [](https://github.com/dcondrey/misterdev/blob/main/CODE_OF_CONDUCT.md) [](https://github.com/sponsors/dcondrey) 
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.
```console
$ 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
```bash
pip install misterdev
# or
uv pip install misterdev
```
Python 3.10 – 3.13. Optional extras add capability without bloating the core install:
```bash
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](https://github.com/dcondrey/misterdev/blob/HEAD/docs/path-to-100.md).
Run it with `misterdev evolve --benchmark --workdir ` (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`](https://github.com/dcondrey/misterdev/blob/HEAD/.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](https://github.com/dcondrey/misterdev/blob/HEAD/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 `.
### 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`](https://github.com/dcondrey/misterdev/blob/HEAD/examples/misterdev-plugin-hello). See [Extending misterdev](#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](https://github.com/Aider-AI/polyglot-benchmark) (Exercism exercises with hidden test suites), `anthropic/claude-sonnet-4-6`:
| Language | Solved | Rate |
| --- | --- | --- |
| JavaScript | 9 / 10 | **90%** |
| Python | 8 / 10 | **80%** |
| Rust | 7 / 10 | **70%** |
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](https://github.com/dcondrey/misterdev/blob/HEAD/docs/benchmark-results.md)**. Test suite: **1,941 passing** — **[docs/TESTING.md](https://github.com/dcondrey/misterdev/blob/HEAD/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:
```console
$ 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:
```console
$ 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:
| Command | What it does |
| --- | --- |
| `misterdev scan ` | 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 tasks, or redirect to `build` if given a goal instead of a path. `--dry-run`, `--force`, `--status`. |
| `misterdev plan [path]` | Analyze the project, recommend work, and compose a plan interactively. `--budget`, `--no-rollback`. |
| `misterdev build [path] [goal]` | The autonomous build/debug/complete workflow. `path` defaults to `.` if a goal is given directly. See flags below. |
Plain `misterdev` with no subcommand launches interactive planning.
misterdev build flags
| Flag | Effect |
| --- | --- |
| `--budget ` | 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 ` | Restrict work to a specific area. |
| `--allow-dirty` | Allow building over uncommitted changes. |
| `--max-tasks ` | Cap the tasks this run will plan/execute (bounds cost). |
The `prompt` is free text or a mode word — `debug`, `complete`, `review`, or `new `.
## 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.
```jsonc
// 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:
```python
# 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`:
```python
# 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)
```
```toml
# 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`](https://github.com/dcondrey/misterdev/blob/HEAD/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.
```yaml
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](https://github.com/dcondrey/misterdev/blob/HEAD/docs/getting-started.md) · [Configuration](https://github.com/dcondrey/misterdev/blob/HEAD/docs/configuration.md) · [Plugins](https://github.com/dcondrey/misterdev/blob/HEAD/docs/plugins.md) · [MCP](https://github.com/dcondrey/misterdev/blob/HEAD/docs/mcp.md). `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
```bash
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](https://github.com/dcondrey/misterdev/blob/HEAD/CONTRIBUTING.md), and open an issue or a pull request on [GitHub](https://github.com/dcondrey/misterdev).
## License
misterdev is **dual-licensed**:
- **[AGPL-3.0-or-later](https://github.com/dcondrey/misterdev/blob/HEAD/LICENSE)** — free for open-source use under the terms of the GNU Affero General Public License.
- **[Commercial license](https://github.com/dcondrey/misterdev/blob/HEAD/COMMERCIAL_LICENSE.md)** — 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.