agent-mcts
Monte Carlo tree search over a coding agent
TLDR
SYNOPSIS
agent-mcts [options] command [arguments]
DESCRIPTION
agent-mcts runs Monte Carlo tree search over a coding agent. Each node is a Git worktree and an agent session. A value command (usually your tests) scores the attempt: exit 0 is a full reward, and a failing run can earn partial credit from a parsed pass ratio. The search spends more episodes on branches that look better. Your current work tree is not modified until apply, which squash-merges the chosen branch.Install it with uv tool install agent-mcts (Python 3.11 or newer). The console script is agent-mcts. The license is MIT. The project classifiers mark it pre-alpha.run prints the agent, the value command, and the budget, then waits for confirmation unless -y is set. While it searches, a tree is drawn in the terminal. Ctrl-C stops the search; the partial tree is still saved. resume continues it. A run that already meets the success threshold tells you to show and apply instead of searching further.Nodes are Git branches under agent-mcts/run/node. An append-only journal records the run so an interrupted search can be inspected.
PARAMETERS
--version
Print the version and exit.run task
Search for a solution to task. The working tree must be a Git repository. The search branches from HEAD and does not see uncommitted changes.-n, --max-nodes n
Episode budget for run, or the new total episode budget for resume. The root baseline is not an episode. The default budget is 12.--max-cost dollars
Cost ceiling in US dollars, for agents that report a dollar cost. The default ceiling is 10.--value command
Command whose exit status and pass ratio score each attempt. When omitted, a test command is detected (pytest, npm test, make test, and similar).--model name
Model override passed to the agent.--agent claude|codex
Which agent backend to drive. Default comes from .agent-mcts.toml or auto-detection. claude is the verified backend. The Codex adapter speaks codex exec and, in this tree, is tested against a fake codex binary.--agent-timeout seconds
Maximum seconds for one agent episode. The default timeout is 600. Must be greater than zero.-j, --parallel n
How many episodes may run at once. Minimum 1.--judge / --no-judge
Also score each attempt with an LLM judge. Cannot be combined with --generate-tests.--generate-tests / --no-generate-tests
Before the search, have the agent write tests from the task and score attempts on those tests as well. Cannot be combined with --judge. Deriving the test command automatically works from a pytest value command; other runners need generate_command in the config file.-y, --yes
On run and resume, do not ask for confirmation.resume [run-id]
Continue a saved run. With no id, the latest run is used. -n and --max-cost raise the total budget. The run keeps the settings it was started with.show [node]
Print the search tree, or the prompt, summary, and evaluation of one node such as n3.--run id
On show and apply, which run to read. Default is the latest run.apply [node]
Squash-merge that node's branch into the working tree and leave the result staged. With no node, the best scored node is used. You review git diff --cached and commit. Apply refuses a dirty work tree.
CONFIGURATION
.agent-mcts.toml in the repository root. Flags override the file for that invocation. A resumed run ignores a newer file and keeps the settings stored with the run.
[value]
command = "pytest tests/ -x -q"
[search]
max_nodes = 20
max_cost_usd = 10.0
parallelism = 3
CAVEATS
The search starts from HEAD. Uncommitted edits are not visible to the agent. apply also refuses to run in a dirty work tree.--judge and --generate-tests cannot both be on. --generate-tests can invent its per-file command only for pytest; other test runners need an explicit command in the config.Agents that do not report a dollar cost are limited by the episode budget only. The Codex backend is not verified against the real Codex CLI in this repository. Kimi is described as planned and is not a working backend yet.apply stages a squash merge. It does not commit.
