ResearchTree

ResearchTree is a framework for systematically exploring and improving AI research ideas through structured search and experimentation.

The goal is not just to make one improvement to a codebase. The goal is to support repeated search over code changes:

• keep a baseline source tree that acts as the search root
• spin out candidate worktrees
• evaluate each candidate with the same scorer and objective wrapper
• preserve run outputs so promising branches can be compared and revisited

Layout

• examples/parameter_golf/: end-to-end example of this workflow for OpenAI's Parameter Golf challenge
• examples/synthetic_regression/: fast synthetic example for cheap search iterations
• treegit/: TreeGit checkout used to manage search branches and worktrees

Search Loop

At a high level, the loop in this repo is:

1. Start from a baseline training script.
2. Create candidate branches and worktrees with TreeGit.
3. Apply one concrete model or training change per candidate.
4. Score that candidate with a fixed local proxy.
5. Keep the best descendants and continue expanding.

Clone

Clone with submodules so treegit/ is present immediately:

git clone --recurse-submodules https://github.com/rishabhgoel0213/ResearchTree.git

If you already cloned without submodules:

git submodule update --init --recursive

Usage

The runnable examples in this repo live under examples/. Start there for the scorer, objective wrapper, MCTS configs, and usage notes:

• examples/parameter_golf/README.md
• examples/synthetic_regression/README.md

Containers

This repo includes a first-pass example runtime workflow driven by a container.toml in each example directory.

• shared image logic lives in docker/Dockerfile
• the Docker launcher lives in scripts/container.py
• a parallel Nix launcher lives in scripts/container_nix.py
• each example declares its runtime in examples/*/container.toml

The two launchers share the same container.toml format but differ in how isolated the workspace is:

• scripts/container.py uses Docker/Podman-managed workspaces and volumes
• scripts/container_nix.py uses a persistent copied workspace under ~/.cache/researchtree-container-nix/ and runs commands in a Nix shell
• both support the same high-level entrypoints such as build, run, shell, and treegit
• both can target either an example name under examples/ or an arbitrary directory path containing a valid container.toml

The current model is intentionally simple:

• the repo is copied into a per-example Docker workspace volume at launch time
• only explicitly configured large directories are bind-mounted from the host into that copied workspace
• the container home directory is also kept in a Docker volume, while host ~/.codex/ is mounted into it for auth/config reuse
• each example's .pixi/ directory is overlaid with a Docker volume so Pixi environments stay on a Linux filesystem
• OS-level tools such as git, tmux, python3, and pixi come from the shared image
• Codex CLI itself is installed in the shared image
• Python/package dependencies still come from each example's pixi.toml
• example-local setup hooks such as pixi run download-data come from container.toml

Before using the launchers, create the local helper virtualenv once and activate it:

python3 setup.py
source .venv/bin/activate

That environment is used for repo helper scripts such as scripts/container.py and scripts/container_nix.py.

Build the image for an example:

python3 scripts/container.py build synthetic_regression

Run an example shell after any configured setup steps:

python3 scripts/container.py shell synthetic_regression

Run a specific command inside the example container:

python3 scripts/container.py run synthetic_regression -- \
  pixi run python score.py ./src --json

Prepare the Parameter Golf container and data cache:

python3 scripts/container.py run parameter_golf --setup-only

The container workspace is disposable and isolated from the host checkout, so generated .treegit/, worktrees, artifacts, and similar churn stay inside Docker-managed volumes instead of showing up in the base repository.

For a Nix-backed workflow with the same container.toml, use the parallel launcher:

python3 scripts/container_nix.py build synthetic_regression
python3 scripts/container_nix.py shell synthetic_regression

To run a single MCTS step in Parameter Golf from a fresh staged workspace:

python3 scripts/container.py treegit parameter_golf init
python3 scripts/container.py treegit parameter_golf commit -m "baseline snapshot"
python3 scripts/container.py treegit parameter_golf mcts init --config ../mcts/smoke.json
python3 scripts/container.py treegit parameter_golf mcts step
python3 scripts/container.py treegit parameter_golf mcts best

The same flow also works with scripts/container_nix.py treegit ... if you want the Nix-backed path instead of Docker.

The checked-in example configs pin platform = "linux/amd64" because the current Pixi manifests target linux-64.

Codex CLI is installed in the shared image, and the launcher mounts host ~/.codex/ into the container so authenticated Codex-driven MCTS runs can work inside the container as well.