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.
Files changed (41) hide show
  1. agent_mcts-0.1.0/.github/workflows/ci.yml +30 -0
  2. agent_mcts-0.1.0/.github/workflows/release.yml +29 -0
  3. agent_mcts-0.1.0/.gitignore +23 -0
  4. agent_mcts-0.1.0/CONTRIBUTING.md +45 -0
  5. agent_mcts-0.1.0/LICENSE +21 -0
  6. agent_mcts-0.1.0/PKG-INFO +157 -0
  7. agent_mcts-0.1.0/README.md +127 -0
  8. agent_mcts-0.1.0/demo/demo.gif +0 -0
  9. agent_mcts-0.1.0/demo/demo.tape +44 -0
  10. agent_mcts-0.1.0/demo/setup-toy-repo.sh +34 -0
  11. agent_mcts-0.1.0/docs/design.md +64 -0
  12. agent_mcts-0.1.0/docs/good-first-issues.md +73 -0
  13. agent_mcts-0.1.0/docs/release.md +35 -0
  14. agent_mcts-0.1.0/docs/spikes/2026-08-02-session-fork-worktree.md +59 -0
  15. agent_mcts-0.1.0/pyproject.toml +83 -0
  16. agent_mcts-0.1.0/src/agent_mcts/__init__.py +3 -0
  17. agent_mcts-0.1.0/src/agent_mcts/adapters/__init__.py +12 -0
  18. agent_mcts-0.1.0/src/agent_mcts/adapters/base.py +54 -0
  19. agent_mcts-0.1.0/src/agent_mcts/adapters/claude_code.py +164 -0
  20. agent_mcts-0.1.0/src/agent_mcts/cli.py +223 -0
  21. agent_mcts-0.1.0/src/agent_mcts/core/__init__.py +20 -0
  22. agent_mcts-0.1.0/src/agent_mcts/core/engine.py +196 -0
  23. agent_mcts-0.1.0/src/agent_mcts/core/journal.py +66 -0
  24. agent_mcts-0.1.0/src/agent_mcts/core/model.py +109 -0
  25. agent_mcts-0.1.0/src/agent_mcts/core/prompts.py +68 -0
  26. agent_mcts-0.1.0/src/agent_mcts/core/value.py +76 -0
  27. agent_mcts-0.1.0/src/agent_mcts/core/worktree.py +94 -0
  28. agent_mcts-0.1.0/src/agent_mcts/project.py +110 -0
  29. agent_mcts-0.1.0/src/agent_mcts/py.typed +0 -0
  30. agent_mcts-0.1.0/src/agent_mcts/tui.py +88 -0
  31. agent_mcts-0.1.0/tests/conftest.py +22 -0
  32. agent_mcts-0.1.0/tests/test_claude_adapter.py +193 -0
  33. agent_mcts-0.1.0/tests/test_cli.py +144 -0
  34. agent_mcts-0.1.0/tests/test_engine.py +175 -0
  35. agent_mcts-0.1.0/tests/test_journal.py +70 -0
  36. agent_mcts-0.1.0/tests/test_model.py +67 -0
  37. agent_mcts-0.1.0/tests/test_project.py +77 -0
  38. agent_mcts-0.1.0/tests/test_tui.py +86 -0
  39. agent_mcts-0.1.0/tests/test_value.py +45 -0
  40. agent_mcts-0.1.0/tests/test_worktree.py +75 -0
  41. 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).
@@ -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
+ ![agent-mcts searching, applying the best branch, and the resulting diff](demo/demo.gif)
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
+ ![agent-mcts searching, applying the best branch, and the resulting diff](demo/demo.gif)
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.