{"slug": "show-hn-agent-mcts-monte-carlo-tree-search-on-top-of-claude-code", "title": "Show HN: agent-mcts – Monte Carlo tree search on top of Claude Code", "summary": "An open-source MIT-licensed tool called agent-mcts, at version v0.3, wraps coding agent CLIs such as Claude Code with Monte Carlo Tree Search so agents explore multiple solution branches and backtrack from dead ends instead of running a single linear loop. In the author's benchmark on two harder tasks (npm semver ranges and ISO 8601 durations, 10 runs per setting, Claude Code with haiku and a 5-episode budget), tests-only search beat the first attempt in 0 of 10 runs with a mean change of −2.2 points, while adding a --judge option produced 4 better, 4 same and 2 worse answers for a mean change of −0.1 points at roughly 5× the episodes and wall time. The author reports the judge picks the better of two attempts that both pass visible tests 38 times in 62, and calls better judging the next thing to work on.", "body_md": "**Turn any coding agent into a tree-searching agent.**\n\n`agent-mcts` is an open-source (MIT) test-time search harness that wraps a coding agent CLI with Monte Carlo Tree Search. It is verified with Claude Code; see [Supported agents](#supported-agents) for the rest. Instead of a single trajectory that either works or doesn't, your agent explores multiple solution branches, backtracks from dead ends, and concentrates budget on the most promising path.\n\n**Status: v0.3.** Early but real — the full loop (search → live tree → apply) works today with Claude Code. A Codex CLI adapter ships too, but so far it has only been tested against a fake `codex` binary. Built in the open; star the repo to follow along, or [jump in](#contributing) — early contributors shape the architecture.\n\nNot yet, on the tasks measured so far ([bench/](https://github.com/natsu0529/agent-mcts/blob/main/bench/README.md), v0.3.0, Claude Code with `haiku`, 5-episode budget). Each answer is scored on hidden tests the agent never sees, and compared with the first attempt of the same run, which is what a single agent run would have returned. Two harder tasks (npm semver ranges, ISO 8601 durations), 10 runs per setting:\n\n|  | answer better than the first attempt | same | worse | mean change | wall time | \n|---|---|---|---|---|---|\n| agent-mcts, tests only | 0 | 9 | 1 | −2.2 pt | ~5 min | \n| agent-mcts, with `--judge` | 4 | 4 | 2 | −0.1 pt | ~23 min | \n\nWhat the per-run numbers show:\n\n- **The judge rescues some failures that tests miss, and loses some good answers.** First attempts that passed the visible tests but scored 73% and 85% on the hidden ones became 86% and 90%. In another run the judge replaced a 91% first attempt with a 68% one it scored higher.\n- **The judge's ranking is the limit.** Between two attempts that both pass the visible tests, it picks the better one 38 times in 62.\n- **Tests-only search is close to a single run.** It stops at the first attempt that passes the visible tests, which was the first attempt in 9 of 10 runs.\n- **The judge costs 5× the episodes and about 5× the wall time.**\n\nAn earlier, smaller measurement on three easier tasks looked better (99% with the judge against 90% for a single attempt), but there every first attempt in the judge runs already scored 98% or more, so it never tested this case. Better judging is the next thing to work on ([full report](https://github.com/natsu0529/agent-mcts/blob/main/bench/results/REPORT.md)).\n\nProduction coding agents (Claude Code, Codex, Kimi, ...) run a **single linear loop**: act, observe, retry in place. No branching, no backtracking, no principled exploration.\n\nResearch shows search helps: [SWE-Search (ICLR 2025)](https://arxiv.org/abs/2410.20285) reported a ~23% relative improvement on SWE-bench by adding MCTS on top of software agents. But that result lives in a research framework — there is no tool that brings it to the agent you already use.\n\n`agent-mcts` closes that gap:\n\n- **Bring your own agent.** A thin adapter layer speaks to each agent's headless mode (`claude -p` ;`codex exec` untested against the real CLI;`kimi -p` planned). The search engine never knows which agent it's driving.\n- **Real MCTS, not best-of-N.** UCT selection, expansion, evaluation, backup. Budget flows toward branches that look promising, away from dead ends.\n- **State you can trust.** Every node is an isolated`git worktree` + a forked agent session. Your working tree is never touched until*you* apply a result.\n- **Terminal-native.** Watch the tree grow live in your terminal. 100% Python, no browser required.\n\n```\nuv tool install agent-mcts\ncd your-project\nagent-mcts run \"fix the flaky test in tests/test_auth.py\"\nagent-mcts run --agent codex \"fix the flaky test in tests/test_auth.py\"   # untested with the real Codex CLI\n```\n\nThe run auto-detects your installed agent and your test command, then shows the plan before spending anything:\n\n```\nAgent: claude · Value: pytest -x -q · Budget: 12 nodes / $10.00\nProceed? [y/N]\n```\n\nWhile searching, the tree grows live in your terminal (real output):\n\n```\ntask: fix the flaky test in tests/test_auth.py\nrun 20260802-190219 · episodes 3/12 · cost $0.31/$10.00\n✓ n0 [r=0.00 Q=0.42 N=4]\n├── ✓ n1 [r=0.67 Q=0.78 N=2] mocked the clock in the auth fixture\n│   └── ● n3 [r=? Q=0.00 N=0] expanding…\n└── ✗ n2 [r=0.00 Q=0.00 N=1] sleep-based fix (tests timed out)\n```\n\nWhen it finishes (or when you Ctrl-C — MCTS is anytime, the partial tree is saved):\n\n```\nagent-mcts show        # inspect the tree; `show n3` prints a node's prompt, summary, evaluation\nagent-mcts resume      # continue the latest run where it stopped (`resume -n 20` raises the budget)\nagent-mcts apply       # stage the best node's changes (squash merge — you review and commit)\nagent-mcts apply n2    # ...or pick a different branch\n┌─────────────────────────────┐\n                │        search engine        │   UCT selection · expansion\n                │   (agent-agnostic, Python)  │   hybrid value fn · backup\n                └──────────────┬──────────────┘\n                               │ AgentBackend protocol\n            ┌──────────────────┼──────────────────┐\n            ▼                  ▼                  ▼\n     claude adapter      codex adapter      kimi adapter\n      (claude -p)        (codex exec)        (kimi -p)\n       verified          fake-tested          planned\n```\n\n- **Node = (git worktree, agent session).** Filesystem state branches via worktrees; conversation state branches via session forking (native on Claude Code, context-injection fallback elsewhere).\n- **Value function = your tests.** Exit 0 scores 1.0; a failing run earns partial credit by pass ratio (read from pytest, jest, cargo test, go test and JUnit-style summaries), and the failing output is fed into children's revision prompts.`pytest` /`npm test` /`make test` are picked up automatically. Add`--judge` to have an LLM score each attempt's diff as well — see[LLM judge](https://github.com/natsu0529/agent-mcts/blob/main/docs/configuration.md#llm-judge) .\n- **Every node is a git branch** (`agent-mcts/<run>/<node>` ), so`apply` is an ordinary squash merge and everything is auditable after the fact. Worktrees are disposable; branches are the record.\n- **Every state change is journaled** (append-only jsonl per run), so an interrupted search is still a valid, inspectable tree.\n\n| Agent | Headless | Session fork | Status | \n|---|---|---|---|\n| Claude Code | `claude -p` | native ( `--fork-session` ) | ✅ v0.1, verified | \n| Codex CLI | `codex exec --json` | context injection | v0.2, tested only against a fake `codex` binary | \n| Kimi CLI | `kimi -p` | context injection | planned (v0.4) | \n| Gemini CLI, OpenCode, ... |  |  | [adapter PRs welcome!](#contributing) | \n\nZero config required. When you need it, `.agent-mcts.toml`:\n\n```\nagent = \"claude\"                  # or \"codex\"\n\n[value]\ncommand = \"pytest tests/ -x -q\"   # exit code + pass ratio → score in [0, 1]\njudge = true                      # also score each attempt with an LLM judge\n\n[search]\nmax_nodes = 20                    # episode budget\nmax_cost_usd = 10.0\nparallelism = 3                   # episodes in flight at once (`-j`)\n```\n\nCLI flags (`--agent`, `-n`, `--max-cost`, `--value`, `--model`, `--agent-timeout`, `--judge/--no-judge`, `-j/--parallel`) override the file.\n\n**Python projects managed with uv:** the value command runs inside fresh worktrees, which don't inherit your virtualenv — use `command = \"uv run pytest -q\"` (or pass `--value \"uv run pytest -q\"`) so each worktree resolves its own environment.\n\nEvery option, the [LLM judge](https://github.com/natsu0529/agent-mcts/blob/main/docs/configuration.md#llm-judge), [parallel runs](https://github.com/natsu0529/agent-mcts/blob/main/docs/configuration.md#running-in-parallel), [resuming](https://github.com/natsu0529/agent-mcts/blob/main/docs/configuration.md#resuming-a-run) and how [failures, cost and timeouts](https://github.com/natsu0529/agent-mcts/blob/main/docs/configuration.md#failures-cost-and-timeouts) are handled: [docs/configuration.md](https://github.com/natsu0529/agent-mcts/blob/main/docs/configuration.md).\n\nSearch hyperparameters are first-class: this is built by an MCTS researcher and meant to double as a research harness for test-time search over real software tasks.\n\n-  **v0.1** — Claude Code adapter, UCT engine, worktree state, test-based value fn, live TUI\n-  **v0.2** — Codex CLI adapter, episode-count budget for agents that report no dollar cost, recoverable timed-out and interrupted episodes\n-  **v0.3** — LLM-as-judge value fn, final head-to-head selection, sibling ranking,`resume` , parallel expansion, selection policy knobs\n-  **v0.4** — Kimi CLI adapter, in-agent activation (`/tree` inside Claude Code via MCP), search-tree export + richer visualization, benchmark mode (same task, N agents, compare trees)\n\nThis project is **open source under the MIT license** and developed fully in the open — issues, design discussions, and PRs all happen here on GitHub. Contributions are welcome from day one.\n\nThe highest-impact contribution is an **agent adapter**: a few hundred lines implementing the [`AgentBackend` protocol](https://github.com/natsu0529/agent-mcts/blob/main/src/agent_mcts/adapters/base.py) for your favorite CLI agent, with no need to touch the search core. Use the [Claude Code adapter](https://github.com/natsu0529/agent-mcts/blob/main/src/agent_mcts/adapters/claude_code.py) as the reference, and the fake-binary pattern in [its tests](https://github.com/natsu0529/agent-mcts/blob/main/tests/test_claude_adapter.py) to keep CI free of API calls. See [CONTRIBUTING.md](https://github.com/natsu0529/agent-mcts/blob/main/CONTRIBUTING.md) for setup.\n\nAlso welcome: bug reports, docs, benchmark tasks, and arguing with our UCT constants.\n\n[MIT](https://github.com/natsu0529/agent-mcts/blob/main/LICENSE) — do whatever you want, just keep the notice.", "url": "https://wpnews.pro/news/show-hn-agent-mcts-monte-carlo-tree-search-on-top-of-claude-code", "canonical_source": "https://github.com/natsu0529/agent-mcts", "published_at": "2026-11-21 13:53:08+00:00", "updated_at": "2026-11-21 14:13:46.602624+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-research"], "entities": ["agent-mcts", "Claude Code", "Codex CLI", "Kimi", "SWE-Search", "SWE-bench"], "also_reported_by": [], "takeaway": "agent-mcts v0.3 adds UCT-based MCTS with git-worktree-isolated nodes on top of Claude Code, but its own 10-run benchmark shows tests-only search improved 0 of 10 answers (−2.2 points mean) and the --judge variant improved 4 and worsened 2 (−0.1 points) at about 5× the wall time.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/show-hn-agent-mcts-monte-carlo-tree-search-on-top-of-claude-code", "markdown": "https://wpnews.pro/news/show-hn-agent-mcts-monte-carlo-tree-search-on-top-of-claude-code.md", "text": "https://wpnews.pro/news/show-hn-agent-mcts-monte-carlo-tree-search-on-top-of-claude-code.txt", "jsonld": "https://wpnews.pro/news/show-hn-agent-mcts-monte-carlo-tree-search-on-top-of-claude-code.jsonld"}}