Tool

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.

Works with claude codecodex cligitpytestjest

88
Spark score
out of 100
Updated today
Source checked Nov 22, 2026
Version 0.4.0
Models
claude

Add to Favorites

Why it matters

Find and inspect candidate code changes through tree search before applying a selected branch.

Outcomes

What it gets done

01

Explore alternative fixes in isolated worktrees

02

Score attempts using project tests and optional diff judging

03

Inspect or resume a saved search

04

Stage a selected branch for review and commit

Source

Get it from source

Spark does not host a copy of it.

Open source

Reports

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.

agent-mcts searching, applying the best branch, and the resulting diff

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 codex binary. 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 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.

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 test are picked up automatically. Add --generate-tests to have an agent write extra tests from the task before the search and score every attempt on them too (generated tests), or --judge to have an LLM score each attempt's diff (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.

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 in bench/
  • v0.5 - 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)

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.