{"id":51504935,"url":"https://github.com/dcondrey/misterdev","last_synced_at":"2026-07-07T23:01:26.407Z","repository":{"id":369555810,"uuid":"1290300769","full_name":"dcondrey/misterdev","owner":"dcondrey","description":"An autonomous, extensible LLM build-orchestrator. Pluggable tools/gates/targets via entry points; agentic MCP tool use incl. hosted gateways (Glama).","archived":false,"fork":false,"pushed_at":"2026-07-05T21:22:48.000Z","size":2951,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T23:08:15.879Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcondrey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-05T19:59:00.000Z","updated_at":"2026-07-05T21:22:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dcondrey/misterdev","commit_stats":null,"previous_names":["dcondrey/misterdev"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dcondrey/misterdev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcondrey%2Fmisterdev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcondrey%2Fmisterdev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcondrey%2Fmisterdev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcondrey%2Fmisterdev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcondrey","download_url":"https://codeload.github.com/dcondrey/misterdev/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcondrey%2Fmisterdev/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35245324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-07T23:01:25.621Z","updated_at":"2026-07-07T23:01:26.401Z","avatar_url":"https://github.com/dcondrey.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/dcondrey/misterdev/main/assets/logo.gif\" alt=\"misterdev\" width=\"220\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003emisterdev\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAn 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.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/misterdev/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/misterdev\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/misterdev/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/misterdev\" alt=\"Python versions\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--3.0-blue\" alt=\"License: AGPL-3.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/dcondrey/misterdev/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/dcondrey/misterdev/ci.yml?branch=main\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://glama.ai/mcp/servers/dcondrey/misterdev\"\u003e\u003cimg src=\"https://glama.ai/mcp/servers/dcondrey/misterdev/badges/score.svg\" alt=\"misterdev MCP server\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e ·\n  \u003ca href=\"#what-it-does\"\u003eWhat it does\u003c/a\u003e ·\n  \u003ca href=\"#cli-reference\"\u003eCLI\u003c/a\u003e ·\n  \u003ca href=\"#extending-misterdev\"\u003eExtending\u003c/a\u003e ·\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e ·\n  \u003ca href=\"#development\"\u003eDevelopment\u003c/a\u003e ·\n  \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\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, **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.\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### 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## CLI reference\n\n**Don't want to remember flags?** If the first argument isn't a subcommand,\nmisterdev treats the whole line as plain English, maps it to an action with its\nown model, shows you a preview, and asks before anything mutating:\n\n```console\n$ misterdev \"fix the failing tests but keep it cheap, and run stuff in parallel\"\n  → I'll run: misterdev build . fix the failing tests --budget 5 --parallel\n    proceed? [Y/n]\n```\n\nThe flag-based commands below still work exactly as written, for scripts and\npower users. The `misterdev` command drives everything:\n\n| Command | What it does |\n| --- | --- |\n| `misterdev scan \u003cdir\u003e` | 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 (or a specific `--task`) tasks for a project. `--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] [prompt]` | The autonomous build/debug/complete workflow. See flags below. |\n\nPlain `misterdev` with no subcommand launches interactive planning.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emisterdev build\u003c/code\u003e flags\u003c/strong\u003e\u003c/summary\u003e\n\n| Flag | Effect |\n| --- | --- |\n| `--budget \u003cfloat\u003e` | 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 \u003carea\u003e` | Restrict work to a specific area. |\n| `--allow-dirty` | Allow building over uncommitted changes. |\n| `--max-tasks \u003cn\u003e` | 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 \u003cdescription\u003e`.\n\u003c/details\u003e\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. Requires 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) -\u003e 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\nDrop 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.\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 \u0026 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\u003cp align=\"center\"\u003e\n  Built by \u003cstrong\u003eDavid Condrey\u003c/strong\u003e ·\n  \u003ca href=\"https://github.com/dcondrey/misterdev\"\u003egithub.com/dcondrey/misterdev\u003c/a\u003e\u003cbr\u003e\n  \u003csub\u003eThe static mark lives at \u003ccode\u003eassets/logo.svg\u003c/code\u003e.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcondrey%2Fmisterdev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcondrey%2Fmisterdev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcondrey%2Fmisterdev/lists"}