Explore alternative code fixes with MCTS
Explore alternative code fixes with agent-mcts, a terminal MCTS harness that branches coding sessions into isolated git worktrees.
0.4.0Add to Favorites
Why it matters
Find and inspect candidate code changes through tree search before applying a selected branch.
Outcomes
What it gets done
Explore alternative fixes in isolated worktrees
Score attempts using project tests and optional diff judging
Inspect or resume a saved search
Stage a selected branch for review and commit
Source
Get it from source
Spark does not host a copy of it.
Open sourceReports
Agent outcome reports
No reports yet
Overview
agent-mcts wraps a coding agent CLI in Monte Carlo Tree Search, evaluating alternative code changes in isolated git worktrees. It supports inspection, resuming, and applying a selected branch; Claude Code is verified, while the Codex adapter has only been exercised with a fake binary. Use it to explore and compare alternative code fixes against your project tests before staging a result. Account for search cost and fallible judging: the reported harder-task measurements did not show an average gain over the first attempt.
What it does
agent-mcts wraps a coding agent CLI in Monte Carlo Tree Search so a programming task can explore alternative solution branches, backtrack from dead ends, and direct its budget toward promising attempts. It uses UCT selection, expansion, evaluation, and backup rather than simply collecting independent answers. The harness is written in Python, runs in the terminal, and is available under the MIT license.
Each search node combines an isolated git worktree with a forked agent session. Filesystem changes branch through worktrees, while conversation state uses native session forking with Claude Code or context injection elsewhere. Your working tree stays untouched until you apply a selected result. Every node also has a git branch, and an append-only JSONL journal records state changes so interrupted searches remain inspectable.
When to use - and when NOT to
Use it when you want to explore multiple code changes for the same task and evaluate them using your project's tests. A flaky-test fix is one documented example. The live tree lets you inspect alternatives instead of following only a single coding trajectory.
Treat answer quality and search cost as practical tradeoffs. The reported harder-task measurements did not show an average improvement over the first attempt: tests-only search was close to a single run, while judging rescued some failures but also selected worse answers. Those measurements used Claude Code with haiku and a limited episode budget. Adding a judge increased both episodes and wall time by about a factor of five. Do not assume branching guarantees a better solution or that judge scores reliably distinguish correct answers.
Claude Code is the verified integration. The Codex CLI adapter has only been exercised against a fake codex binary, so real Codex CLI compatibility remains unverified. Choose accordingly when deciding whether to run the harness with your existing agent.
Inputs and outputs
Give the run command a natural-language coding task inside your project. The harness detects an installed agent and a test command, then presents its plan before spending budget. Install and start with the documented commands:
uv tool install agent-mcts
cd your-project
agent-mcts run "fix the flaky test in tests/test_auth.py"
During execution, the terminal displays the growing tree, episode use, cost, and node evaluations. Interrupting a run saves its partial tree. The show command inspects the tree or an individual node's prompt, summary, and evaluation; resume continues the latest run and can raise its budget. The apply command stages the best node's changes through a squash merge, or you can select a different branch. You review and commit the resulting changes yourself.
Integrations
The agent backend uses Claude Code's headless mode and native session fork. Codex uses its headless execution interface with context injection, subject to the compatibility limitation above. An adapter protocol separates the search engine from the CLI it drives.
The value function uses your tests: a successful exit receives full credit, while failures receive partial credit from parsed pass ratios. Supported summary formats include pytest, jest, cargo test, go test, and JUnit-style output. Failing output becomes input to child revision prompts. The harness automatically picks up pytest, npm test, or make test; an optional LLM judge can also score each attempt's diff.
Configuration lives in .agent-mcts.toml. It controls agent choice, the value command, judge use, node and cost budgets, and concurrent episodes. CLI flags override file settings and expose model, timeout, and parallel execution options. For Python projects managed with uv, use a value command such as uv run pytest -q: fresh worktrees do not inherit your virtual environment, so each worktree must resolve its own environment.
Who it's for
The harness serves developers using coding agent CLIs who want inspectable search branches and control over which changes enter their project. It also supports MCTS researchers studying test-time search on real software tasks, with configurable search hyperparameters and recorded branch histories.
Source README
agent-mcts 🌳
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 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.4. 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
codexbinary. Built in the open; star the repo to follow along, or jump in - early contributors shape the architecture.
Does it help?
With generated tests, yes, on tasks with a written spec; on a vague bug report, so far only as much as the judge (bench/, 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 tasks with a spec (npm semver ranges, ISO 8601 durations), 20 runs per setting:
| answer better than the first attempt | same | worse | mean change | worst answer | wall time | cost per run | |
|---|---|---|---|---|---|---|---|
| agent-mcts, tests only | 1 | 18 | 1 | −0.6 pt | 39% | ~5 min | $0.43 |
agent-mcts, with --judge |
11 | 5 | 4 | +5.4 pt | 68% | ~21 min | $1.81 |
agent-mcts, with --generate-tests |
16 | 2 | 2 | +4.8 pt | 81% | ~19 min | $2.44 |
What the per-run numbers show:
- Generated tests beat a single run. Before the search, an agent writes tests from the task and the code as it stands; every attempt is then scored on them. The answer improved in 16 of 20 runs and got worse in 2, by 1 and 4 points. Mean share of hidden tests passed: 88% for the first attempt, 93% for the answer returned.
- The gain mostly comes from revisions. A failing generated test tells the next attempt what to fix: 32 of 40 revisions raised the hidden score, against 13 of 40 with the judge. In 13 of 20 runs the answer beat all three first attempts.
- The judge reads diffs, and that is not enough. Its mean gain comes from rescuing two broken first attempts (19% and 37%). Over the other 18 runs it averaged +0.0 pt, and in one it replaced a 91% first attempt with a 68% one.
- Tests-only search is close to a single run. It stops at the first attempt that passes the visible tests.
A vague bug report is harder. A third task gives the agent only a user's report that Japanese text misaligns a table (10 runs per setting). The test writer made the same mistake as the bug, measuring alignment in characters, so the unfixed code passed its tests and every fix failed them, and v0.4.0 returned the unfixed code in all 10 runs. agent-mcts now offers the unchanged code only when every attempt does worse on your own tests, and warns when the generated tests preferred it. On the same ten trees that gives 4 runs better than the first attempt and none worse (88% → 93%), level with the judge (3 better, none worse, 91% → 93%).
Caveats: three small tasks, one model, 10 to 20 runs per setting. Details in the full report.
Why
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) 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 execuntested against the real CLI;kimi -pplanned). 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.
Quickstart
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
How it works
┌─────────────────────────────┐
│ 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 testare picked up automatically. Add--generate-teststo have an agent write extra tests from the task before the search and score every attempt on them too (generated tests), or--judgeto have an LLM score each attempt's diff (LLM judge). - Every node is a git branch (
agent-mcts/<run>/<node>), soapplyis 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.
Supported agents
| 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.5) |
| Gemini CLI, OpenCode, ... | adapter PRs welcome! |
Configuration
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]
generate_tests = true # also score on tests an agent writes from the task
[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, --generate-tests, --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, generated tests, the LLM judge, parallel runs, resuming and how failures, cost and timeouts are handled: 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.
Roadmap
- 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 - generated-tests value fn (
--generate-tests), hidden-test benchmark inbench/ - v0.5 - Kimi CLI adapter, in-agent activation (
/treeinside Claude Code via MCP), search-tree export + richer visualization, benchmark mode (same task, N agents, compare trees)
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.