# Show HN: agent-mcts – Monte Carlo tree search on top of Claude Code

> Source: <https://github.com/natsu0529/agent-mcts>
> Published: 2026-11-21 13:53:08+00:00

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

**Turn any coding agent into a tree-searching agent.**

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

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

Not 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:

|  | answer better than the first attempt | same | worse | mean change | wall time | 
|---|---|---|---|---|---|
| agent-mcts, tests only | 0 | 9 | 1 | −2.2 pt | ~5 min | 
| agent-mcts, with `--judge` | 4 | 4 | 2 | −0.1 pt | ~23 min | 

What the per-run numbers show:

- **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.
- **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.
- **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.
- **The judge costs 5× the episodes and about 5× the wall time.**

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

Production coding agents (Claude Code, Codex, Kimi, ...) run a **single linear loop**: act, observe, retry in place. No branching, no backtracking, no principled exploration.

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

`agent-mcts` closes that gap:

- **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.
- **Real MCTS, not best-of-N.** UCT selection, expansion, evaluation, backup. Budget flows toward branches that look promising, away from dead ends.
- **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.
- **Terminal-native.** Watch the tree grow live in your terminal. 100% Python, no browser required.

```
uv tool install agent-mcts
cd your-project
agent-mcts run "fix the flaky test in tests/test_auth.py"
agent-mcts run --agent codex "fix the flaky test in tests/test_auth.py"   # untested with the real Codex CLI
```

The run auto-detects your installed agent and your test command, then shows the plan before spending anything:

```
Agent: claude · Value: pytest -x -q · Budget: 12 nodes / $10.00
Proceed? [y/N]
```

While searching, the tree grows live in your terminal (real output):

```
task: fix the flaky test in tests/test_auth.py
run 20260802-190219 · episodes 3/12 · cost $0.31/$10.00
✓ n0 [r=0.00 Q=0.42 N=4]
├── ✓ n1 [r=0.67 Q=0.78 N=2] mocked the clock in the auth fixture
│   └── ● n3 [r=? Q=0.00 N=0] expanding…
└── ✗ n2 [r=0.00 Q=0.00 N=1] sleep-based fix (tests timed out)
```

When it finishes (or when you Ctrl-C — MCTS is anytime, the partial tree is saved):

```
agent-mcts show        # inspect the tree; `show n3` prints a node's prompt, summary, evaluation
agent-mcts resume      # continue the latest run where it stopped (`resume -n 20` raises the budget)
agent-mcts apply       # stage the best node's changes (squash merge — you review and commit)
agent-mcts apply n2    # ...or pick a different branch
┌─────────────────────────────┐
                │        search engine        │   UCT selection · expansion
                │   (agent-agnostic, Python)  │   hybrid value fn · backup
                └──────────────┬──────────────┘
                               │ AgentBackend protocol
            ┌──────────────────┼──────────────────┐
            ▼                  ▼                  ▼
     claude adapter      codex adapter      kimi adapter
      (claude -p)        (codex exec)        (kimi -p)
       verified          fake-tested          planned
```

- **Node = (git worktree, agent session).** Filesystem state branches via worktrees; conversation state branches via session forking (native on Claude Code, context-injection fallback elsewhere).
- **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) .
- **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.
- **Every state change is journaled** (append-only jsonl per run), so an interrupted search is still a valid, inspectable tree.

| Agent | Headless | Session fork | Status | 
|---|---|---|---|
| Claude Code | `claude -p` | native ( `--fork-session` ) | ✅ v0.1, verified | 
| Codex CLI | `codex exec --json` | context injection | v0.2, tested only against a fake `codex` binary | 
| Kimi CLI | `kimi -p` | context injection | planned (v0.4) | 
| Gemini CLI, OpenCode, ... |  |  | [adapter PRs welcome!](#contributing) | 

Zero config required. When you need it, `.agent-mcts.toml`:

```
agent = "claude"                  # or "codex"

[value]
command = "pytest tests/ -x -q"   # exit code + pass ratio → score in [0, 1]
judge = true                      # also score each attempt with an LLM judge

[search]
max_nodes = 20                    # episode budget
max_cost_usd = 10.0
parallelism = 3                   # episodes in flight at once (`-j`)
```

CLI flags (`--agent`, `-n`, `--max-cost`, `--value`, `--model`, `--agent-timeout`, `--judge/--no-judge`, `-j/--parallel`) override the file.

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

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

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

-  **v0.1** — Claude Code adapter, UCT engine, worktree state, test-based value fn, live TUI
-  **v0.2** — Codex CLI adapter, episode-count budget for agents that report no dollar cost, recoverable timed-out and interrupted episodes
-  **v0.3** — LLM-as-judge value fn, final head-to-head selection, sibling ranking,`resume` , parallel expansion, selection policy knobs
-  **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)

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

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

Also welcome: bug reports, docs, benchmark tasks, and arguing with our UCT constants.

[MIT](https://github.com/natsu0529/agent-mcts/blob/main/LICENSE) — do whatever you want, just keep the notice.
