agent-mcts 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_mcts-0.1.0/.github/workflows/ci.yml +30 -0
- agent_mcts-0.1.0/.github/workflows/release.yml +29 -0
- agent_mcts-0.1.0/.gitignore +23 -0
- agent_mcts-0.1.0/CONTRIBUTING.md +45 -0
- agent_mcts-0.1.0/LICENSE +21 -0
- agent_mcts-0.1.0/PKG-INFO +157 -0
- agent_mcts-0.1.0/README.md +127 -0
- agent_mcts-0.1.0/demo/demo.gif +0 -0
- agent_mcts-0.1.0/demo/demo.tape +44 -0
- agent_mcts-0.1.0/demo/setup-toy-repo.sh +34 -0
- agent_mcts-0.1.0/docs/design.md +64 -0
- agent_mcts-0.1.0/docs/good-first-issues.md +73 -0
- agent_mcts-0.1.0/docs/release.md +35 -0
- agent_mcts-0.1.0/docs/spikes/2026-08-02-session-fork-worktree.md +59 -0
- agent_mcts-0.1.0/pyproject.toml +83 -0
- agent_mcts-0.1.0/src/agent_mcts/__init__.py +3 -0
- agent_mcts-0.1.0/src/agent_mcts/adapters/__init__.py +12 -0
- agent_mcts-0.1.0/src/agent_mcts/adapters/base.py +54 -0
- agent_mcts-0.1.0/src/agent_mcts/adapters/claude_code.py +164 -0
- agent_mcts-0.1.0/src/agent_mcts/cli.py +223 -0
- agent_mcts-0.1.0/src/agent_mcts/core/__init__.py +20 -0
- agent_mcts-0.1.0/src/agent_mcts/core/engine.py +196 -0
- agent_mcts-0.1.0/src/agent_mcts/core/journal.py +66 -0
- agent_mcts-0.1.0/src/agent_mcts/core/model.py +109 -0
- agent_mcts-0.1.0/src/agent_mcts/core/prompts.py +68 -0
- agent_mcts-0.1.0/src/agent_mcts/core/value.py +76 -0
- agent_mcts-0.1.0/src/agent_mcts/core/worktree.py +94 -0
- agent_mcts-0.1.0/src/agent_mcts/project.py +110 -0
- agent_mcts-0.1.0/src/agent_mcts/py.typed +0 -0
- agent_mcts-0.1.0/src/agent_mcts/tui.py +88 -0
- agent_mcts-0.1.0/tests/conftest.py +22 -0
- agent_mcts-0.1.0/tests/test_claude_adapter.py +193 -0
- agent_mcts-0.1.0/tests/test_cli.py +144 -0
- agent_mcts-0.1.0/tests/test_engine.py +175 -0
- agent_mcts-0.1.0/tests/test_journal.py +70 -0
- agent_mcts-0.1.0/tests/test_model.py +67 -0
- agent_mcts-0.1.0/tests/test_project.py +77 -0
- agent_mcts-0.1.0/tests/test_tui.py +86 -0
- agent_mcts-0.1.0/tests/test_value.py +45 -0
- agent_mcts-0.1.0/tests/test_worktree.py +75 -0
- agent_mcts-0.1.0/uv.lock +355 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
lint:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- uses: astral-sh/setup-uv@v6
|
|
14
|
+
- run: uv sync --group dev
|
|
15
|
+
- run: uv run ruff check .
|
|
16
|
+
- run: uv run ruff format --check .
|
|
17
|
+
- run: uv run pyright
|
|
18
|
+
|
|
19
|
+
test:
|
|
20
|
+
runs-on: ubuntu-latest
|
|
21
|
+
strategy:
|
|
22
|
+
matrix:
|
|
23
|
+
python-version: ["3.11", "3.12", "3.13", "3.14"]
|
|
24
|
+
steps:
|
|
25
|
+
- uses: actions/checkout@v4
|
|
26
|
+
- uses: astral-sh/setup-uv@v6
|
|
27
|
+
with:
|
|
28
|
+
python-version: ${{ matrix.python-version }}
|
|
29
|
+
- run: uv sync --group dev
|
|
30
|
+
- run: uv run pytest
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags: ["v*"]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
test:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
steps:
|
|
11
|
+
- uses: actions/checkout@v4
|
|
12
|
+
- uses: astral-sh/setup-uv@v6
|
|
13
|
+
- run: uv sync --group dev
|
|
14
|
+
- run: uv run ruff check .
|
|
15
|
+
- run: uv run pyright
|
|
16
|
+
- run: uv run pytest
|
|
17
|
+
|
|
18
|
+
publish:
|
|
19
|
+
needs: test
|
|
20
|
+
runs-on: ubuntu-latest
|
|
21
|
+
environment: pypi
|
|
22
|
+
permissions:
|
|
23
|
+
id-token: write # PyPI trusted publishing (no API token needed)
|
|
24
|
+
contents: read
|
|
25
|
+
steps:
|
|
26
|
+
- uses: actions/checkout@v4
|
|
27
|
+
- uses: astral-sh/setup-uv@v6
|
|
28
|
+
- run: uv build
|
|
29
|
+
- run: uv publish --trusted-publishing always
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
dist/
|
|
6
|
+
build/
|
|
7
|
+
|
|
8
|
+
# Environments
|
|
9
|
+
.venv/
|
|
10
|
+
venv/
|
|
11
|
+
|
|
12
|
+
# Tooling caches
|
|
13
|
+
.pytest_cache/
|
|
14
|
+
.ruff_cache/
|
|
15
|
+
.pyright/
|
|
16
|
+
|
|
17
|
+
# agent-mcts run artifacts
|
|
18
|
+
.agent-mcts/
|
|
19
|
+
|
|
20
|
+
# OS / editor
|
|
21
|
+
.DS_Store
|
|
22
|
+
.idea/
|
|
23
|
+
.vscode/
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for your interest! This project is developed fully in the open, and contributions are welcome from day one — including while we're still pre-alpha.
|
|
4
|
+
|
|
5
|
+
## Development setup
|
|
6
|
+
|
|
7
|
+
You need [uv](https://docs.astral.sh/uv/) and Python 3.11+.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
git clone https://github.com/natsu0529/mcts-llm-agent
|
|
11
|
+
cd mcts-llm-agent
|
|
12
|
+
uv sync --group dev
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Run the checks (these are exactly what CI runs):
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
uv run ruff check . # lint
|
|
19
|
+
uv run ruff format . # format
|
|
20
|
+
uv run pyright # type check (strict mode)
|
|
21
|
+
uv run pytest # tests
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Try the CLI from your checkout:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
uv run agent-mcts --version
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## What to contribute
|
|
31
|
+
|
|
32
|
+
- **Agent adapters** are the highest-impact contribution: a small module implementing the `AgentBackend` protocol ([src/agent_mcts/adapters/base.py](src/agent_mcts/adapters/base.py)) for a coding agent CLI (Codex, Kimi, Gemini CLI, OpenCode, ...), without touching the search core. Use the Claude Code adapter as the reference implementation, and test against a fake binary (see `tests/test_claude_adapter.py`) so CI never calls a real API.
|
|
33
|
+
- Bug reports, docs fixes, and benchmark tasks are always welcome.
|
|
34
|
+
- Search-engine changes (selection policy, value functions) are welcome too — please include the reasoning, and numbers if you have them.
|
|
35
|
+
|
|
36
|
+
## Pull requests
|
|
37
|
+
|
|
38
|
+
- Keep PRs focused: one topic per PR.
|
|
39
|
+
- All code is typed (`pyright` strict must pass) and formatted with `ruff format`.
|
|
40
|
+
- Add or update tests for behavior changes.
|
|
41
|
+
- If you're unsure whether an idea fits, open an issue first — it saves everyone time.
|
|
42
|
+
|
|
43
|
+
## License
|
|
44
|
+
|
|
45
|
+
By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).
|
agent_mcts-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 natsu0529
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR IN CONNECTION WITH
|
|
21
|
+
THE SOFTWARE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-mcts
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Turn any coding agent into a tree-searching agent — an MCTS test-time search harness for Claude Code, Codex CLI, Kimi CLI, and more.
|
|
5
|
+
Project-URL: Homepage, https://github.com/natsu0529/mcts-llm-agent
|
|
6
|
+
Project-URL: Repository, https://github.com/natsu0529/mcts-llm-agent
|
|
7
|
+
Project-URL: Issues, https://github.com/natsu0529/mcts-llm-agent/issues
|
|
8
|
+
Author: natsu0529
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: agents,claude-code,coding-agent,llm,mcts,monte-carlo-tree-search,test-time-search
|
|
12
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
23
|
+
Classifier: Topic :: Software Development
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.11
|
|
26
|
+
Requires-Dist: pydantic>=2.7
|
|
27
|
+
Requires-Dist: rich>=13.7
|
|
28
|
+
Requires-Dist: typer>=0.12
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# agent-mcts 🌳
|
|
32
|
+
|
|
33
|
+
**Turn any coding agent into a tree-searching agent.**
|
|
34
|
+
|
|
35
|
+
`agent-mcts` is an open-source (MIT) test-time search harness that wraps coding agents — Claude Code, Codex CLI, Kimi CLI — with Monte Carlo Tree Search. 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.
|
|
36
|
+
|
|
37
|
+

|
|
38
|
+
|
|
39
|
+
> **Status: v0.1.** Early but real — the full loop (search → live tree → apply) works today with Claude Code. Built in the open; star the repo to follow along, or [jump in](#contributing) — early contributors shape the architecture.
|
|
40
|
+
|
|
41
|
+
## Why
|
|
42
|
+
|
|
43
|
+
Production coding agents (Claude Code, Codex, Kimi, ...) run a **single linear loop**: act, observe, retry in place. No branching, no backtracking, no principled exploration.
|
|
44
|
+
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
`agent-mcts` closes that gap:
|
|
48
|
+
|
|
49
|
+
- **Bring your own agent.** A thin adapter layer speaks to each agent's headless mode (`claude -p`, `codex exec`, `kimi -p`). The search engine never knows which agent it's driving.
|
|
50
|
+
- **Real MCTS, not best-of-N.** UCT selection, expansion, evaluation, backup. Budget flows toward branches that look promising, away from dead ends.
|
|
51
|
+
- **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.
|
|
52
|
+
- **Terminal-native.** Watch the tree grow live in your terminal. 100% Python, no browser required.
|
|
53
|
+
|
|
54
|
+
## Quickstart
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
uv tool install agent-mcts
|
|
58
|
+
cd your-project
|
|
59
|
+
agent-mcts run "fix the flaky test in tests/test_auth.py"
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The run auto-detects your installed agent and your test command, then shows the plan before spending anything:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
Agent: claude · Value: pytest -x -q · Budget: 12 nodes / $10.00
|
|
66
|
+
Proceed? [y/N]
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
While searching, the tree grows live in your terminal (real output):
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
task: fix the flaky test in tests/test_auth.py
|
|
73
|
+
run 20260802-190219 · episodes 3/12 · cost $0.31/$10.00
|
|
74
|
+
✓ n0 [r=0.00 Q=0.42 N=4]
|
|
75
|
+
├── ✓ n1 [r=0.67 Q=0.78 N=2] mocked the clock in the auth fixture
|
|
76
|
+
│ └── ● n3 [r=? Q=0.00 N=0] expanding…
|
|
77
|
+
└── ✗ n2 [r=0.00 Q=0.00 N=1] sleep-based fix (tests timed out)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
When it finishes (or when you Ctrl-C — MCTS is anytime, the partial tree is saved):
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
agent-mcts show # inspect the tree; `show n3` prints a node's prompt, summary, evaluation
|
|
84
|
+
agent-mcts apply # stage the best node's changes (squash merge — you review and commit)
|
|
85
|
+
agent-mcts apply n2 # ...or pick a different branch
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## How it works
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
┌─────────────────────────────┐
|
|
92
|
+
│ search engine │ UCT selection · expansion
|
|
93
|
+
│ (agent-agnostic, Python) │ hybrid value fn · backup
|
|
94
|
+
└──────────────┬──────────────┘
|
|
95
|
+
│ AgentBackend protocol
|
|
96
|
+
┌──────────────────┼──────────────────┐
|
|
97
|
+
▼ ▼ ▼
|
|
98
|
+
claude adapter codex adapter kimi adapter
|
|
99
|
+
(claude -p) (codex exec) (kimi -p)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
- **Node = (git worktree, agent session).** Filesystem state branches via worktrees; conversation state branches via session forking (native on Claude Code, context-injection fallback elsewhere).
|
|
103
|
+
- **Value function = your tests.** Exit 0 scores 1.0; a pytest-style summary earns partial credit by pass ratio, and the failing output is fed into children's revision prompts. `pytest` / `npm test` / `make test` are picked up automatically. (LLM-as-judge lands in v0.2.)
|
|
104
|
+
- **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.
|
|
105
|
+
- **Every state change is journaled** (append-only jsonl per run), so an interrupted search is still a valid, inspectable tree.
|
|
106
|
+
|
|
107
|
+
## Supported agents
|
|
108
|
+
|
|
109
|
+
| Agent | Headless | Session fork | Status |
|
|
110
|
+
|---|---|---|---|
|
|
111
|
+
| Claude Code | `claude -p` | native (`--fork-session`) | ✅ v0.1 |
|
|
112
|
+
| Codex CLI | `codex exec` | resume + context injection | planned (v0.2) |
|
|
113
|
+
| Kimi CLI | `kimi -p` | context injection | planned (v0.3) |
|
|
114
|
+
| Gemini CLI, OpenCode, ... | | | [adapter PRs welcome!](#contributing) |
|
|
115
|
+
|
|
116
|
+
## Configuration
|
|
117
|
+
|
|
118
|
+
Zero config required. When you need it, `.agent-mcts.toml`:
|
|
119
|
+
|
|
120
|
+
```toml
|
|
121
|
+
agent = "claude"
|
|
122
|
+
model = "haiku" # optional agent-model override
|
|
123
|
+
|
|
124
|
+
[value]
|
|
125
|
+
command = "pytest tests/ -x -q" # exit code + pass ratio → score in [0, 1]
|
|
126
|
+
|
|
127
|
+
[search]
|
|
128
|
+
max_nodes = 20 # episode budget
|
|
129
|
+
max_cost_usd = 10.0 # hard cost ceiling
|
|
130
|
+
c_uct = 1.414 # UCT exploration constant — yes, it's exposed
|
|
131
|
+
root_width = 3 # diverse first attempts under the root
|
|
132
|
+
refine_width = 2 # revision children per node
|
|
133
|
+
max_depth = 3
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
CLI flags (`-n`, `--max-cost`, `--value`, `--model`) override the file. If your `claude` binary lives somewhere unusual, point `AGENT_MCTS_CLAUDE_BIN` at it.
|
|
137
|
+
|
|
138
|
+
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.
|
|
139
|
+
|
|
140
|
+
## Roadmap
|
|
141
|
+
|
|
142
|
+
- [x] **v0.1** — Claude Code adapter, UCT engine, worktree state, test-based value fn, live TUI
|
|
143
|
+
- [ ] **v0.2** — Codex CLI adapter (+ `--agent` registry), LLM-as-judge value fn, `resume`, parallel expansion
|
|
144
|
+
- [ ] **v0.3** — Kimi CLI adapter, in-agent activation (`/tree` inside Claude Code via MCP)
|
|
145
|
+
- [ ] **v0.4** — search-tree export + richer visualization, benchmark mode (same task, N agents, compare trees)
|
|
146
|
+
|
|
147
|
+
## Contributing
|
|
148
|
+
|
|
149
|
+
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.
|
|
150
|
+
|
|
151
|
+
The highest-impact contribution is an **agent adapter**: a few hundred lines implementing the [`AgentBackend` protocol](src/agent_mcts/adapters/base.py) for your favorite CLI agent, with no need to touch the search core. Use the [Claude Code adapter](src/agent_mcts/adapters/claude_code.py) as the reference, and the fake-binary pattern in [its tests](tests/test_claude_adapter.py) to keep CI free of API calls. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup.
|
|
152
|
+
|
|
153
|
+
Also welcome: bug reports, docs, benchmark tasks, and arguing with our UCT constants.
|
|
154
|
+
|
|
155
|
+
## License
|
|
156
|
+
|
|
157
|
+
[MIT](LICENSE) — do whatever you want, just keep the notice.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# agent-mcts 🌳
|
|
2
|
+
|
|
3
|
+
**Turn any coding agent into a tree-searching agent.**
|
|
4
|
+
|
|
5
|
+
`agent-mcts` is an open-source (MIT) test-time search harness that wraps coding agents — Claude Code, Codex CLI, Kimi CLI — with Monte Carlo Tree Search. 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.
|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
> **Status: v0.1.** Early but real — the full loop (search → live tree → apply) works today with Claude Code. Built in the open; star the repo to follow along, or [jump in](#contributing) — early contributors shape the architecture.
|
|
10
|
+
|
|
11
|
+
## Why
|
|
12
|
+
|
|
13
|
+
Production coding agents (Claude Code, Codex, Kimi, ...) run a **single linear loop**: act, observe, retry in place. No branching, no backtracking, no principled exploration.
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
`agent-mcts` closes that gap:
|
|
18
|
+
|
|
19
|
+
- **Bring your own agent.** A thin adapter layer speaks to each agent's headless mode (`claude -p`, `codex exec`, `kimi -p`). The search engine never knows which agent it's driving.
|
|
20
|
+
- **Real MCTS, not best-of-N.** UCT selection, expansion, evaluation, backup. Budget flows toward branches that look promising, away from dead ends.
|
|
21
|
+
- **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.
|
|
22
|
+
- **Terminal-native.** Watch the tree grow live in your terminal. 100% Python, no browser required.
|
|
23
|
+
|
|
24
|
+
## Quickstart
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
uv tool install agent-mcts
|
|
28
|
+
cd your-project
|
|
29
|
+
agent-mcts run "fix the flaky test in tests/test_auth.py"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The run auto-detects your installed agent and your test command, then shows the plan before spending anything:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
Agent: claude · Value: pytest -x -q · Budget: 12 nodes / $10.00
|
|
36
|
+
Proceed? [y/N]
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
While searching, the tree grows live in your terminal (real output):
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
task: fix the flaky test in tests/test_auth.py
|
|
43
|
+
run 20260802-190219 · episodes 3/12 · cost $0.31/$10.00
|
|
44
|
+
✓ n0 [r=0.00 Q=0.42 N=4]
|
|
45
|
+
├── ✓ n1 [r=0.67 Q=0.78 N=2] mocked the clock in the auth fixture
|
|
46
|
+
│ └── ● n3 [r=? Q=0.00 N=0] expanding…
|
|
47
|
+
└── ✗ n2 [r=0.00 Q=0.00 N=1] sleep-based fix (tests timed out)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
When it finishes (or when you Ctrl-C — MCTS is anytime, the partial tree is saved):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
agent-mcts show # inspect the tree; `show n3` prints a node's prompt, summary, evaluation
|
|
54
|
+
agent-mcts apply # stage the best node's changes (squash merge — you review and commit)
|
|
55
|
+
agent-mcts apply n2 # ...or pick a different branch
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## How it works
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
┌─────────────────────────────┐
|
|
62
|
+
│ search engine │ UCT selection · expansion
|
|
63
|
+
│ (agent-agnostic, Python) │ hybrid value fn · backup
|
|
64
|
+
└──────────────┬──────────────┘
|
|
65
|
+
│ AgentBackend protocol
|
|
66
|
+
┌──────────────────┼──────────────────┐
|
|
67
|
+
▼ ▼ ▼
|
|
68
|
+
claude adapter codex adapter kimi adapter
|
|
69
|
+
(claude -p) (codex exec) (kimi -p)
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
- **Node = (git worktree, agent session).** Filesystem state branches via worktrees; conversation state branches via session forking (native on Claude Code, context-injection fallback elsewhere).
|
|
73
|
+
- **Value function = your tests.** Exit 0 scores 1.0; a pytest-style summary earns partial credit by pass ratio, and the failing output is fed into children's revision prompts. `pytest` / `npm test` / `make test` are picked up automatically. (LLM-as-judge lands in v0.2.)
|
|
74
|
+
- **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.
|
|
75
|
+
- **Every state change is journaled** (append-only jsonl per run), so an interrupted search is still a valid, inspectable tree.
|
|
76
|
+
|
|
77
|
+
## Supported agents
|
|
78
|
+
|
|
79
|
+
| Agent | Headless | Session fork | Status |
|
|
80
|
+
|---|---|---|---|
|
|
81
|
+
| Claude Code | `claude -p` | native (`--fork-session`) | ✅ v0.1 |
|
|
82
|
+
| Codex CLI | `codex exec` | resume + context injection | planned (v0.2) |
|
|
83
|
+
| Kimi CLI | `kimi -p` | context injection | planned (v0.3) |
|
|
84
|
+
| Gemini CLI, OpenCode, ... | | | [adapter PRs welcome!](#contributing) |
|
|
85
|
+
|
|
86
|
+
## Configuration
|
|
87
|
+
|
|
88
|
+
Zero config required. When you need it, `.agent-mcts.toml`:
|
|
89
|
+
|
|
90
|
+
```toml
|
|
91
|
+
agent = "claude"
|
|
92
|
+
model = "haiku" # optional agent-model override
|
|
93
|
+
|
|
94
|
+
[value]
|
|
95
|
+
command = "pytest tests/ -x -q" # exit code + pass ratio → score in [0, 1]
|
|
96
|
+
|
|
97
|
+
[search]
|
|
98
|
+
max_nodes = 20 # episode budget
|
|
99
|
+
max_cost_usd = 10.0 # hard cost ceiling
|
|
100
|
+
c_uct = 1.414 # UCT exploration constant — yes, it's exposed
|
|
101
|
+
root_width = 3 # diverse first attempts under the root
|
|
102
|
+
refine_width = 2 # revision children per node
|
|
103
|
+
max_depth = 3
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
CLI flags (`-n`, `--max-cost`, `--value`, `--model`) override the file. If your `claude` binary lives somewhere unusual, point `AGENT_MCTS_CLAUDE_BIN` at it.
|
|
107
|
+
|
|
108
|
+
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.
|
|
109
|
+
|
|
110
|
+
## Roadmap
|
|
111
|
+
|
|
112
|
+
- [x] **v0.1** — Claude Code adapter, UCT engine, worktree state, test-based value fn, live TUI
|
|
113
|
+
- [ ] **v0.2** — Codex CLI adapter (+ `--agent` registry), LLM-as-judge value fn, `resume`, parallel expansion
|
|
114
|
+
- [ ] **v0.3** — Kimi CLI adapter, in-agent activation (`/tree` inside Claude Code via MCP)
|
|
115
|
+
- [ ] **v0.4** — search-tree export + richer visualization, benchmark mode (same task, N agents, compare trees)
|
|
116
|
+
|
|
117
|
+
## Contributing
|
|
118
|
+
|
|
119
|
+
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.
|
|
120
|
+
|
|
121
|
+
The highest-impact contribution is an **agent adapter**: a few hundred lines implementing the [`AgentBackend` protocol](src/agent_mcts/adapters/base.py) for your favorite CLI agent, with no need to touch the search core. Use the [Claude Code adapter](src/agent_mcts/adapters/claude_code.py) as the reference, and the fake-binary pattern in [its tests](tests/test_claude_adapter.py) to keep CI free of API calls. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup.
|
|
122
|
+
|
|
123
|
+
Also welcome: bug reports, docs, benchmark tasks, and arguing with our UCT constants.
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
[MIT](LICENSE) — do whatever you want, just keep the notice.
|
|
Binary file
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# VHS tape for the README demo GIF — https://github.com/charmbracelet/vhs
|
|
2
|
+
#
|
|
3
|
+
# Prep (once):
|
|
4
|
+
# brew install vhs
|
|
5
|
+
# uv tool install <repo> # agent-mcts on PATH
|
|
6
|
+
# uv tool install pytest # value fn for the toy repo
|
|
7
|
+
# ./demo/setup-toy-repo.sh /tmp/agent-mcts-demo
|
|
8
|
+
# Record:
|
|
9
|
+
# cd /tmp/agent-mcts-demo && vhs /path/to/repo/demo/demo.tape
|
|
10
|
+
# Then copy demo.gif into demo/ and reference it from the README.
|
|
11
|
+
|
|
12
|
+
Output demo.gif
|
|
13
|
+
|
|
14
|
+
Set FontSize 15
|
|
15
|
+
Set Width 1100
|
|
16
|
+
Set Height 650
|
|
17
|
+
Set Theme "Catppuccin Mocha"
|
|
18
|
+
Set TypingSpeed 40ms
|
|
19
|
+
Set WaitTimeout 300s
|
|
20
|
+
|
|
21
|
+
# invisible setup: tool paths + claude binary override if the shell needs them
|
|
22
|
+
Hide
|
|
23
|
+
Type `export PATH="$HOME/.local/bin:$PATH"`
|
|
24
|
+
Enter
|
|
25
|
+
Type `clear`
|
|
26
|
+
Enter
|
|
27
|
+
Show
|
|
28
|
+
|
|
29
|
+
Type `agent-mcts run "fix the broken add() in calc.py"`
|
|
30
|
+
Enter
|
|
31
|
+
Sleep 2s
|
|
32
|
+
Type "y"
|
|
33
|
+
Enter
|
|
34
|
+
|
|
35
|
+
# wait for the search to finish (the closing hint line mentions `apply`)
|
|
36
|
+
Wait+Screen /agent-mcts apply/
|
|
37
|
+
Sleep 2s
|
|
38
|
+
|
|
39
|
+
Type `agent-mcts apply`
|
|
40
|
+
Enter
|
|
41
|
+
Sleep 2s
|
|
42
|
+
Type `git diff --cached`
|
|
43
|
+
Enter
|
|
44
|
+
Sleep 6s
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Create a tiny repo with a failing test, for recording the README demo.
|
|
3
|
+
# Usage: ./demo/setup-toy-repo.sh /tmp/agent-mcts-demo
|
|
4
|
+
set -eu
|
|
5
|
+
|
|
6
|
+
dir="${1:?usage: setup-toy-repo.sh <dir>}"
|
|
7
|
+
rm -rf "$dir"
|
|
8
|
+
mkdir -p "$dir"
|
|
9
|
+
cd "$dir"
|
|
10
|
+
|
|
11
|
+
git init -q
|
|
12
|
+
cat > calc.py << 'EOF'
|
|
13
|
+
def add(a, b):
|
|
14
|
+
return a - b
|
|
15
|
+
EOF
|
|
16
|
+
cat > test_calc.py << 'EOF'
|
|
17
|
+
from calc import add
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def test_add():
|
|
21
|
+
assert add(1, 2) == 3
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def test_add_negative():
|
|
25
|
+
assert add(-1, -2) == -3
|
|
26
|
+
EOF
|
|
27
|
+
cat > pytest.ini << 'EOF'
|
|
28
|
+
[pytest]
|
|
29
|
+
EOF
|
|
30
|
+
git add -A
|
|
31
|
+
git -c user.name=demo -c user.email=demo@example.com commit -qm "init"
|
|
32
|
+
|
|
33
|
+
echo "Toy repo ready at $dir"
|
|
34
|
+
echo "Record with: cd $dir && vhs <repo>/demo/demo.tape"
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# agent-mcts design notes
|
|
2
|
+
|
|
3
|
+
Living document. Decisions land here with their reasoning; supersedes nothing silently.
|
|
4
|
+
|
|
5
|
+
## Node = (git worktree, agent session)
|
|
6
|
+
|
|
7
|
+
Validated by [the WP2 spike](spikes/2026-08-02-session-fork-worktree.md):
|
|
8
|
+
|
|
9
|
+
- **Filesystem state** branches via `git worktree` — one worktree per node, one branch per
|
|
10
|
+
node (`agent-mcts/<run>/<node>`). After the agent finishes an expansion, the manager
|
|
11
|
+
commits everything in the worktree onto the node's branch, so children can branch from
|
|
12
|
+
an immutable snapshot and `apply` is an ordinary merge.
|
|
13
|
+
- **Conversation state** branches via session forking (`claude -p --resume <id>
|
|
14
|
+
--fork-session`), which works across directories and at any depth.
|
|
15
|
+
|
|
16
|
+
## Expansion granularity: one node = one complete attempt
|
|
17
|
+
|
|
18
|
+
One node expansion = one headless agent episode (`claude -p <prompt>`) that runs until the
|
|
19
|
+
agent considers the task done, followed by evaluation (value function) of the resulting
|
|
20
|
+
worktree.
|
|
21
|
+
|
|
22
|
+
- **Root's children** explore *diverse approaches*: each child prompt asks the agent to
|
|
23
|
+
attempt the task, optionally steered away from approaches its siblings already took.
|
|
24
|
+
- **Deeper children** are *revisions*: the child inherits the parent's conversation and
|
|
25
|
+
code state, and its prompt includes the parent's evaluation feedback (failing tests,
|
|
26
|
+
judge critique) with the instruction to repair or improve.
|
|
27
|
+
|
|
28
|
+
Why not step-level (one node = one agent action), as some research systems do:
|
|
29
|
+
|
|
30
|
+
1. A headless CLI call is naturally a whole episode; capping it to single actions fights
|
|
31
|
+
the agent harness and its own planning.
|
|
32
|
+
2. The test-based value signal is only meaningful after a complete attempt — mid-attempt
|
|
33
|
+
the tests are red for uninteresting reasons.
|
|
34
|
+
3. Episode nodes keep the tree shallow (depth 2–4, tens of nodes), which is what a
|
|
35
|
+
several-minutes-per-node, dollars-per-run budget can afford.
|
|
36
|
+
|
|
37
|
+
This makes the MCTS action space "revision strategies" rather than "editor actions" —
|
|
38
|
+
the same flavor as SWE-Search's iterative refinement, and a natural fit for UCT: siblings
|
|
39
|
+
compete on approach, depth accumulates refinement.
|
|
40
|
+
|
|
41
|
+
## MCTS bookkeeping
|
|
42
|
+
|
|
43
|
+
Classic UCT statistics live on the node: `visits` (N), `value_sum` (W), `q = W/N`.
|
|
44
|
+
A node's own evaluation is `reward` ∈ [0, 1]; `backup()` propagates a value from a node
|
|
45
|
+
up to the root. Selection policy (UCT constant, expansion width, etc.) lives in the
|
|
46
|
+
search engine, not the data model.
|
|
47
|
+
|
|
48
|
+
## Persistence: append-only journal
|
|
49
|
+
|
|
50
|
+
`.agent-mcts/runs/<run-id>/tree.jsonl` — first line is run metadata, then one full node
|
|
51
|
+
snapshot per line, last-wins per node id. Crash-safe (append-only), trivially replayable,
|
|
52
|
+
and doubles as the export format for future visualization. MCTS is anytime: whatever is
|
|
53
|
+
in the journal when you Ctrl-C is a valid, resumable tree.
|
|
54
|
+
|
|
55
|
+
## Run artifacts layout
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
<repo>/.agent-mcts/
|
|
59
|
+
runs/<run-id>/tree.jsonl # the tree
|
|
60
|
+
worktrees/<run-id>/<node-id>/ # per-node worktrees (removable; branches survive)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The tool never touches the user's `.gitignore`; it appends `.agent-mcts/` to
|
|
64
|
+
`.git/info/exclude` instead.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Issues to file at launch
|
|
2
|
+
|
|
3
|
+
Drafts for the initial `good first issue` / `help wanted` batch. File these on
|
|
4
|
+
GitHub when the repo goes public so contributors have obvious entry points.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## [help wanted] Codex CLI adapter
|
|
9
|
+
|
|
10
|
+
**Labels:** `adapter`, `help wanted`
|
|
11
|
+
|
|
12
|
+
Implement `AgentBackend` for OpenAI's Codex CLI, the v0.2 flagship feature.
|
|
13
|
+
|
|
14
|
+
- Protocol: `src/agent_mcts/adapters/base.py` (~50 lines to implement)
|
|
15
|
+
- Reference implementation: `src/agent_mcts/adapters/claude_code.py`
|
|
16
|
+
- Mechanics: headless mode is `codex exec --json`; resuming is
|
|
17
|
+
`codex exec resume <session-id>`. Codex has no `--fork-session` equivalent,
|
|
18
|
+
so either verify that resuming the same session twice diverges safely, or
|
|
19
|
+
start fresh sessions and inject parent context into the prompt (see the
|
|
20
|
+
fallback discussion in `docs/design.md`).
|
|
21
|
+
- Definition of done: `agent-mcts run --agent codex` completes a search on a
|
|
22
|
+
toy repo; adapter tests use a fake `codex` binary (see
|
|
23
|
+
`tests/test_claude_adapter.py` for the pattern — no API calls in CI).
|
|
24
|
+
|
|
25
|
+
Note: the CLI currently hardcodes the Claude adapter; this issue includes
|
|
26
|
+
adding an `--agent` option backed by a simple adapter registry.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## [help wanted] Kimi CLI adapter
|
|
31
|
+
|
|
32
|
+
**Labels:** `adapter`, `help wanted`
|
|
33
|
+
|
|
34
|
+
Same shape as the Codex issue. Headless mode is
|
|
35
|
+
`kimi -p --output-format stream-json --yolo`; session forking is unverified,
|
|
36
|
+
so context injection is the expected route.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## [good first issue] Gemini CLI adapter
|
|
41
|
+
|
|
42
|
+
**Labels:** `adapter`, `good first issue`
|
|
43
|
+
|
|
44
|
+
Gemini CLI has a straightforward headless mode (`gemini -p`). Follow the
|
|
45
|
+
adapter guide in CONTRIBUTING.md; the fake-binary test pattern makes this a
|
|
46
|
+
self-contained few-hundred-line PR.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## [good first issue] `agent-mcts resume`
|
|
51
|
+
|
|
52
|
+
**Labels:** `cli`, `good first issue`
|
|
53
|
+
|
|
54
|
+
The journal is already append-only and replayable (`journal.load()` rebuilds a
|
|
55
|
+
tree from any interrupted run), and `SearchEngine` accepts a pre-populated
|
|
56
|
+
tree. What's missing is the CLI plumbing: a `resume [run-id]` command that
|
|
57
|
+
loads the latest journal, reconstructs the `WorktreeManager` state (recreate
|
|
58
|
+
worktrees from node branches), and continues the loop under the original
|
|
59
|
+
budget. Design note: worktrees are disposable by design — branches are the
|
|
60
|
+
durable record.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## [help wanted] LLM-as-judge value function
|
|
65
|
+
|
|
66
|
+
**Labels:** `search`, `help wanted`
|
|
67
|
+
|
|
68
|
+
`CommandValueFunction` scores by tests alone. Add a judge that asks an LLM to
|
|
69
|
+
score a node's diff against the task (0–1), and a combiner
|
|
70
|
+
(`w_test * test + w_judge * judge`). This is the hybrid value design from
|
|
71
|
+
SWE-Search (ICLR 2025). Keep it behind `[value] judge = true` in
|
|
72
|
+
`.agent-mcts.toml`, defaulting off. Needs a design discussion first —
|
|
73
|
+
comment on the issue before building.
|