English | 한국어

ResearchTree

Every branch is an experiment. Every PR is its lab note.

Turn your Git branches and pull requests into a living map of your research,
a tree that grows from your first implementation, one experiment at a time.

How it works · Get started · Training API · Open science · Guide

[!NOTE] Available now: the hosted viewer, the VS Code extension, and the Python package (see Install). An Open VSX listing is coming.

See it on a demo project: researchtree-demo, a year of made-up text-to-speech research with five versions, competing hypotheses side by side, and intent and spec documents that evolve with the evidence (repository).

The viewer and the VS Code extension speak Korean and English: they follow your browser (or VS Code) language, and you can switch in Settings. The Python CLI output is still Korean only.

🌱 Why ResearchTree?

Research moves in small steps: you take working code, change one assumption, and see what happens. Those attempts usually end up scattered across dashboards, notebooks, chat threads, and commit messages. Later it is hard to tell which idea came from where, what was adopted, and why the others were dropped.

ResearchTree fixes that with a few rules you already know how to follow:

The viewer reads those pull requests and draws them as a tree. Click any experiment to see its results. There is no database and no server-side cache: GitHub is the only data store.

📸 Screenshots

Version panel: tag date, merged experiments, metrics, and what grew from it	Press-down morph: the camera turns top-down and the islands flatten
Flat view: the same scene seen from above, with only paths, plots and stones left	Sign-in: GitHub or a personal access token

_{Screenshots use sample data.}

🧭 How it works

Branches become a tree

research is the root: your initial implementation, and the line where adopted experiments are merged. Every experiment lives on experiment/<name>. When adopted experiments are merged into research, you tag the merge with the next version, and the tree keeps growing from there.

%%{init: {'gitGraph': {'mainBranchName': 'research'}}}%%
gitGraph
  commit id: "initial implementation" tag: "v1"
  branch experiment/baseline
  commit id: "baseline"
  branch experiment/lr-half
  commit id: "lr 3e-4 → 1.5e-4"
  checkout experiment/baseline
  branch experiment/warmup
  commit id: "add warmup"
  checkout research
  merge experiment/warmup tag: "v2"
  branch experiment/warmup-cosine
  commit id: "cosine schedule"

_{In the tree above, lr-half gets closed (rejected), warmup is adopted and merged as v2, and warmup-cosine starts from v2.}

[!TIP] The root branch name (research) and the experiment prefix (experiment/) are only defaults. You can change both per repository in the viewer's branch settings. Set RESEARCHTREE_PREFIX so the training-script API uses the same prefix.

The PR body is the lab note

Put a single yaml block at the top of the PR body. The viewer reads only the first yaml block. Everything below it is free-form Markdown.

```yaml
parent: experiment/baseline-moshi
hypothesis: Halving the depth-transformer LR reduces early divergence
change: lr 3e-4 → 1.5e-4
metrics:
  val_loss: 2.31
  wer: 0.184
wandb: https://wandb.ai/...
status: rejected
tags: [lr]
```

## Conclusion
Divergence went down, but convergence was too slow. Rejected.

Unknown fields are kept. When ResearchTree rewrites a PR body, it changes only the YAML block and preserves comments, key order, and the Markdown below. A broken YAML block is never overwritten.

# adopt an experiment into research and tag the next version
git switch research && git merge --no-ff experiment/depth-lr-warmup
git tag -a research/v2 -m "v2: adopt warmup" && git push origin research research/v2

# start a new experiment from that version (PR base: research, YAML: parent: research@v2)
git switch -c experiment/warmup-cosine research/v2

# or derive one from another experiment (PR base: the parent experiment)
git switch experiment/baseline-moshi
git switch -c experiment/depth-lr-half

researchtree release        # plan: delete merged branches, archive the rest, keep ones with running children
researchtree release --yes  # archive (revert the branch's commits, merge into research), tag research/vN, push, delete

🏝️ The viewer

_{The viewer needs WebGL. Without it, the tree cannot be drawn.}

🚀 Three ways to use it

One viewer, three hosts. Pick whichever fits your setup.

uv tool install researchtree
researchtree serve                  # opens http://127.0.0.1:7337 in your browser

export RESEARCHTREE_TOKEN=github_pat_...
researchtree serve

🧪 Log from your training script

Add the same package to your training project, and your training script can write straight into the current branch's PR.

import researchtree as rt

rt.log(val_loss=2.31, wer=0.184)        # merge into `metrics` (None deletes a key)
rt.set(wandb=run.url)                   # set any YAML field
rt.conclude("rejected", "Converged too slowly", heading="Conclusion")  # set status + write a "## Conclusion" section

• Never breaks training. If the branch isn't an experiment branch, no PR is found, or GitHub fails, you get a warning and the script keeps running.
• Distributed-safe. It acts only on rank 0 (RANK / LOCAL_RANK).
• Conclusion section. An existing conclusion section is updated in place, whether its heading is English (## Conclusion) or Korean. A new one gets heading (the default is the Korean heading used by the original convention).
• Lossless. It edits only the YAML block, using the same rules and the same test fixtures as the TypeScript viewer.

🧠 Research memory for agents

The same record doubles as memory for coding agents. rt.load() returns the whole PR tree as typed Python objects, versions (islands) → experiments → body sections → commits. An agent starts from a short manifest and drills down only where it needs to, so questions like "how many experiments were rejected per version?" become one-line computations instead of searches through notes.

import researchtree as rt

research = rt.load()                          # the repo of your `origin` remote
print(research.manifest())                    # islands, best results, running work, alerts
e = research["duet-mix"]                      # .hypothesis .metrics .parent .children .conclusion
e.delta("tts_wer"), e.commits()               # vs the parent; commits are read lazily from GitHub
research.experiments.where(status="adopted").best("val_loss")
{v.name: len(v.experiments.where(status="rejected")) for v in research.versions}
research.check()                              # deterministic rules: stale runs, regressions, missing metrics

From a terminal: researchtree memory, researchtree memory v3, researchtree memory duet-mix, --check, --json.

To teach a coding agent the whole workflow (branch and PR conventions, the PR body, rt.log, this memory API, researchtree release), install the bundled skill into your repository:

researchtree skill install    # writes SKILL.md to .claude/skills/researchtree/ and/or .agents/skills/researchtree/

[!NOTE] Inspired by User as Code (Li, 2026), which keeps agent memory as typed Python state plus executable rules. Here the pull requests are the append-only log and the YAML block is already the typed state, so no separate structuring step is needed. GitHub stays the only data store.

Intent and spec documents

Keep why (INTENT.md: goals, claims with ids like N1, non-goals), what the system is now (SPEC.md: decisions only, one feature per section, each opening with a one-line > summary) and evidence (PR bodies) apart. An experiment that changes the design edits SPEC.md on its own branch, so each version's spec holds only adopted designs, and experiments list the claims they test with claims: [N1].

researchtree spec --summary     # the latest design on one page
researchtree spec --diff        # what changed since the previous version
researchtree spec --claims      # each claim with the experiments that tested it

In the viewer, the version panel's Spec tab shows each version's spec in full, as a summary, or as changes since the previous version, with a history per section, and the experiment panel's Spec tab shows what that branch changed. Set other paths in .researchtree.yml on the root branch (spec:, intent:, prefix:). See the guide.

📦 Install

pip install researchtree            # into a training project (or: uv add researchtree)
uv tool install researchtree        # or as a standalone CLI

Optional: pip install "researchtree[keyring]" stores the token in the OS keyring instead of a file.

To install the latest development version from the repository, use pip install git+https://github.com/DarkPyonix/researchtree. The build hook compiles the viewer, so this needs Node and npm.

🔒 Security & privacy

• Your token stays on its host. It lives in browser localStorage (web), the extension host (VS Code, never the webview), or the local Python process (local). It is only ever sent to api.github.com, and every call goes through a path-only API check.
• The auth proxy only exchanges codes. The small Cloudflare Worker turns an OAuth code into a token for the hosted site. It stores and logs nothing, and it accepts only allow-listed origins.
• The local server stays local. It binds to 127.0.0.1, rejects unexpected Host headers (DNS rebinding), requires a per-run session token, and blocks DELETE on its GitHub relay.
• PR bodies are untrusted. Markdown is sanitized with DOMPurify, and a strict CSP allows only bundled scripts. Nothing loads from a CDN at runtime.
• No database. Everything is read from and written to GitHub. Nothing is cached on a server.

🔬 Open science

Every experiment is an ordinary Git branch and every lab note is an ordinary pull request, so the full record of a research project lives in the repository itself: the exact code of each attempt, the hypothesis behind it, the metrics it produced, and why it was adopted or ruled out. Nothing sits in a private notebook or a separate database.

That makes the whole experimental history easy to publish. Make the repository public and you share more than the final result: the path that led to it, including the negative results and abandoned ideas that papers usually leave out. Anyone can check out a branch to reproduce a single experiment, compare it with its parent, or branch off from it to continue the work.

ResearchTree supports open science in this way: transparent, reproducible research whose experiment records can be shared in full.

🛠️ Development

npm install                 # from the repo root
npm run dev                 # web dev server on :5173
npm test                    # vitest
npm run typecheck
npm run build               # web + local + extension builds
npm run package:extension   # .vsix
uv run pytest               # Python tests
uv build                    # Python wheel

The guide covers architecture and details.

🤝 Contributing

Issues and pull requests are welcome. A few conventions:

• Commit messages use Type: Summary on one line, in English and in the imperative mood, for example Feat: Add tree view or Fix: Keep selection on view switch. Types: Feat, Fix, Refactor, Test, Docs, Chore.
• PR-body rules are implemented twice, in TypeScript and Python. Change tests/fixtures/prbody-cases.json first, then make both implementations pass.
• Run the tests and the typecheck for every package you touch.

📄 License

Apache License 2.0 © DarkPyonix