{
  "markdown": "<!-- repo-header:start -->\n<img src=\"https://raw.githubusercontent.com/dcondrey/misterdev/main/assets/logo.gif\" alt=\"misterdev logo\" width=\"120\" align=\"left\">\n\n<h1>misterdev</h1>\n\n<p><strong>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.</strong></p>\n\n<br clear=\"left\">\n\n[![CI](https://img.shields.io/github/actions/workflow/status/dcondrey/misterdev/ci.yml?style=flat-square&labelColor=20232a&branch=main&label=CI)](https://github.com/dcondrey/misterdev/actions/workflows/ci.yml) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14406/badge)](https://www.bestpractices.dev/projects/14406) [![License](https://img.shields.io/github/license/dcondrey/misterdev?style=flat-square&labelColor=20232a&color=007ec6&label=license)](https://github.com/dcondrey/misterdev/blob/main/LICENSE) [![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-Contributor%20Covenant%202.1-6a4c93?style=flat-square&labelColor=20232a)](https://github.com/dcondrey/misterdev/blob/main/CODE_OF_CONDUCT.md) [![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-Sponsor-EA4AAA?style=flat-square&labelColor=20232a)](https://github.com/sponsors/dcondrey) <a href=\"https://pypi.org/project/misterdev/\"><img src=\"https://img.shields.io/pypi/v/misterdev?style=flat-square&labelColor=20232a&color=007ec6\" alt=\"PyPI version\"></a> <a href=\"https://pypi.org/project/misterdev/\"><img src=\"https://img.shields.io/pypi/pyversions/misterdev?style=flat-square&labelColor=20232a&color=007ec6\" alt=\"Python versions\"></a> <a href=\"https://github.com/dcondrey/misterdev/actions/workflows/ci.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/dcondrey/misterdev/ci.yml?branch=main&style=flat-square&labelColor=20232a\" alt=\"CI\"></a>\n<!-- repo-header:end -->\n\n<a href=\"#install\">Install</a> ·\n  <a href=\"#what-it-does\">What it does</a> ·\n  <a href=\"#cli-reference\">CLI</a> ·\n  <a href=\"#extending-misterdev\">Extending</a> ·\n  <a href=\"#configuration\">Configuration</a> ·\n  <a href=\"#development\">Development</a> ·\n  <a href=\"#license\">License</a>\n</p>\n\n---\n\nPoint 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.\n\n```console\n$ misterdev build . \"add rate limiting to the public API\"\n\n  planning   goal → 3 tasks  (model: anthropic/claude-sonnet-4-6, budget $100.00)\n  task 1/3   middleware: token-bucket limiter          api/limiter.py\n    edit     1 hunk applied · syntax ok\n    gates    build GREEN · tests GREEN (142 passed) · lint GREEN · typecheck GREEN\n  task 2/3   wire limiter into request pipeline         api/app.py\n    edit     2 hunks applied\n    gates    build GREEN · tests RED (1 failed) → rolling back, regenerating\n    edit     2 hunks applied (attempt 2)\n    gates    build GREEN · tests GREEN (145 passed) · lint GREEN · typecheck GREEN\n  task 3/3   docs + config surface                      README.md, config.py\n    gates    all GREEN\n\n  done       3/3 tasks · 145 tests green · $0.38 over 11 calls\n```\n\nBecause 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.\n\n## Install\n\n```bash\npip install misterdev\n# or\nuv pip install misterdev\n```\n\nPython 3.10 – 3.13. Optional extras add capability without bloating the core install:\n\n```bash\npip install 'misterdev[local-embeddings]'   # offline semantic context ranking (fastembed, no API key)\npip install 'misterdev[lsp]'                 # LSP semantic-diagnostics gate\npip install 'misterdev[web]'                 # headless-browser web verification gate (+ playwright install chromium)\npip install 'misterdev[mcp]'                 # Model Context Protocol tool-host substrate\n```\n\nExtras are all opt-in and timeout-bounded. When an extra's runtime dependency is absent, the gate it powers SKIPs rather than failing.\n\n## What it does\n\n### Autonomous build loop\n\nGive 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.\n\n### Polyglot symbol-graph context\n\nA 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.\n\n### Correctness gates\n\nEvery 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.\n\n### Dynamic model selection\n\nmisterdev 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.\n\n### Parallel worktrees\n\nDisjoint 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.\n\n### Self-improving\n\nmisterdev 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](docs/path-to-100.md).\n\nRun 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`](.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.\n\nOn 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.\n\n**Two-timescale evolution** *(built; opt-in via `orchestrator.runtime_tooling`; see [docs/two-timescale-evolution.md](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>`.\n\n### Extensibility\n\nTools, 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`](examples/misterdev-plugin-hello). See [Extending misterdev](#extending-misterdev).\n\n### Agentic MCP\n\nmisterdev 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.\n\n## Benchmarks\n\nGate-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`:\n\n| Language | Solved | Rate |\n| --- | --- | --- |\n| JavaScript | 9 / 10 | **90%** |\n| Python | 8 / 10 | **80%** |\n| Rust | 7 / 10 | **70%** |\n\nA 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](docs/benchmark-results.md)**. Test suite: **1,941 passing** — **[docs/TESTING.md](docs/TESTING.md)**.\n\n## CLI reference\n\n**Don't want to remember flags?** Just describe what you want — no project setup\nor devplan required. misterdev routes it with zero friction:\n\n```console\n$ misterdev \"add rate limiting to the public API\"\n  ⠸ Building…\n```\n\nAction words (`add`, `fix`, `implement`, `write`, `create`, …) go straight to\nbuild — no LLM routing call, no confirmation prompt, no ceremony. Query and\nmanagement words (`list`, `status`, `what`, `how`, `check`, `run`, …) are\nmapped with a model call, shown as a preview, and ask before anything mutating:\n\n```console\n$ misterdev \"check what's broken and fix it cheaply, run in parallel\"\n  → I'll run: misterdev build . fix broken tests --budget 5 --parallel\n    proceed? [Y/n]\n```\n\nThe flag-based commands below still work for scripts and power users.\nThe `misterdev` command drives everything:\n\n| Command | What it does |\n| --- | --- |\n| `misterdev scan <dir>` | Discover projects under a directory and register them. |\n| `misterdev list` | List all registered projects. |\n| `misterdev status [path]` | Show a project's tasks and their state. |\n| `misterdev report [path]` | Summarize the latest build's cost/tokens, per-model ledger performance, and the audit trail. Read-only — nothing is re-run. |\n| `misterdev run [path]` | Run pending tasks, or redirect to `build` if given a goal instead of a path. `--dry-run`, `--force`, `--status`. |\n| `misterdev plan [path]` | Analyze the project, recommend work, and compose a plan interactively. `--budget`, `--no-rollback`. |\n| `misterdev build [path] [goal]` | The autonomous build/debug/complete workflow. `path` defaults to `.` if a goal is given directly. See flags below. |\n\nPlain `misterdev` with no subcommand launches interactive planning.\n\n<details>\n<summary><strong><code>misterdev build</code> flags</strong></summary>\n\n| Flag | Effect |\n| --- | --- |\n| `--budget <float>` | Max dollar budget for the run (default 100). |\n| `--commit` | Commit after each completed task. |\n| `--parallel` | Execute independent tasks concurrently in isolated worktrees. |\n| `--dry-run` | Plan only; show tasks without executing. |\n| `--interactive`, `-i` | Wait for confirmation between tasks. |\n| `--no-verify` | Skip the final validation phase. |\n| `--no-suggest` | Skip the suggest scan. |\n| `--no-rollback` | Disable auto-bisect/revert of a regressing task. |\n| `--focus <area>` | Restrict work to a specific area. |\n| `--allow-dirty` | Allow building over uncommitted changes. |\n| `--max-tasks <n>` | Cap the tasks this run will plan/execute (bounds cost). |\n\nThe `prompt` is free text or a mode word — `debug`, `complete`, `review`, or `new <description>`.\n</details>\n\n## Drive it from an AI client (MCP server)\n\nmisterdev also ships **as an MCP server** (`misterdev-mcp`), so you can drive it\nin plain English from Claude Desktop, Claude Code, Cursor, or any MCP client —\nno flags to remember. The client just calls a tool (`build`, `scan`, `status`,\n`list_projects`, `run`); the **entire orchestration runs inside misterdev's own\nprocess** with its own model and context budget, and only a short summary\nreturns to the client — your codebase never enters the client's context window.\n\n```jsonc\n// Claude Desktop config (claude_desktop_config.json)\n{\n  \"mcpServers\": {\n    \"misterdev\": {\n      \"command\": \"misterdev-mcp\",\n      \"env\": { \"OPENROUTER_API_KEY\": \"sk-...\" }\n    }\n  }\n}\n```\n\nThen just ask: *\"Have misterdev add rate limiting to the API, keep it under $5.\"*\nMutating tools (`build`, `run`) refuse a dirty working tree and carry a\nconservative default budget.\n\n**Claude Code integration.** The `build` tool accepts a `spec_text` parameter.\nPass a complete spec written by Claude and misterdev skips its own analysis and\nspec-generation phases, going straight to decompose → execute → verify using\nyour codebase's own gate suite. Claude handles the design; misterdev handles the\nexecution, correctness gates, and rollback:\n\n```python\n# In Claude Code / MCP client\nmisterdev.build(\"/path/to/repo\", spec_text=\"\"\"\nFeature: add a token-bucket rate limiter to /api/v1/*\n...full spec...\n\"\"\")\n```\n\nRequires the `mcp` extra: `pip install 'misterdev[mcp]'`.\n\n## Extending misterdev\n\nA plugin is an ordinary Python package that declares entry points in the `misterdev.*` groups. Install it, and misterdev picks it up — no core edits.\n\nA **tool** is a class; a **gate** is a callable returning a `GateOutcome`:\n\n```python\n# misterdev_plugin_hello.py\nfrom misterdev.core.execution.outcomes import GateOutcome, GREEN, RED\n\n\nclass HelloTool:\n    gather_safe = True  # opt into the agentic gathering loop\n    gather_description = \"Return a friendly greeting for a name.\"\n\n    def __init__(self, config: dict):\n        self.name = config.get(\"name\", \"hello\")\n\n    def execute(self, project, name: str = \"world\", **_ignored):\n        return True, f\"Hello, {name}!\"\n\n\ndef no_shouting_gate(ctx) -> GateOutcome:\n    build = (ctx.commands or {}).get(\"build_command\") or \"\"\n    if build and build.isupper():\n        return GateOutcome(RED, \"build_command is ALL CAPS; please calm down\")\n    return GateOutcome(GREEN)\n```\n\n```toml\n# pyproject.toml — the entry points are the whole contract\n[project.entry-points.\"misterdev.tools\"]\nhello = \"misterdev_plugin_hello:HelloTool\"\n\n[project.entry-points.\"misterdev.gates\"]\nno_shouting = \"misterdev_plugin_hello:no_shouting_gate\"\n```\n\nTargets 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`](examples/misterdev-plugin-hello).\n\n## Configuration\n\nA `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.\n\n```yaml\nname: \"My App\"\nlanguage: \"python\"\nbuild_command: \"python -m compileall -q .\"\ntest_command: \"pytest -q\"\nlint_command: \"ruff check .\"\nllm:\n  provider: \"openrouter\"            # openrouter | anthropic\n  model: \"anthropic/claude-sonnet-4-6\"\n  api_key_env_var: \"OPENROUTER_API_KEY\"\n```\n\nKey knobs:\n\n- **Model & budget** — `llm.model`, provider/failover, and the run's dollar ceiling (also `--budget`).\n- **Gates** — optional gates (adversarial critic, mutation, runtime-smoke, web, vision, goal-check) are off by default and enabled under the `orchestrator.*` keys.\n- **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.\n- **Targets** — a `targets:` block gives a polyglot monorepo per-language build/test/lint, routed per task.\n\n**Guides:** [Getting started](docs/getting-started.md) · [Configuration](docs/configuration.md) · [Plugins](docs/plugins.md) · [MCP](docs/mcp.md). `project.yaml.example` documents every configuration key.\n\n## Requirements\n\n- Python **3.10 – 3.13**\n- **git** (branch-per-task, worktrees, and rollback all run through it)\n- An API key for **OpenRouter** or **Anthropic**\n- 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)\n\n## Development\n\n```bash\ngit clone https://github.com/dcondrey/misterdev\ncd misterdev\nuv sync\nuv run ruff check .\nuv run pytest -q\n```\n\nContributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md), and open an issue or a pull request on [GitHub](https://github.com/dcondrey/misterdev).\n\n## License\n\nmisterdev is **dual-licensed**:\n\n- **[AGPL-3.0-or-later](LICENSE)** — free for open-source use under the terms of the GNU Affero General Public License.\n- **[Commercial license](COMMERCIAL_LICENSE.md)** — for use in a closed-source or proprietary product without AGPL obligations.\n\nChoose the one that fits your project.\n\n---\n\n<p align=\"center\">\n  Built by <strong>David Condrey</strong> ·\n  <a href=\"https://github.com/dcondrey/misterdev\">github.com/dcondrey/misterdev</a><br>\n  <sub>The static mark lives at <code>assets/logo.svg</code>.</sub>\n</p>\n",
  "bytes": 20037,
  "sha": "64c2aaba525b4356ad134dfac500fd2655217872270cda6a6ba14f340e50fd82",
  "repo_slug": "dcondrey/misterdev",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dcondrey_misterdev_5169b7a4/readme"
}