The insight
Running experiments is the core loop of software research — make a change, measure it, keep it or discard it, log it, repeat. Doing this by hand is slow and error-prone. Writing a custom shell script for each project is fragile.
This feature makes the experimental loop a first-class opencode primitive.
What it does
opencode research <goal> scaffolds a workspace and launches an autonomous agent that iterates on a code artifact:
.autoresearch/
├── program.md # your instructions (human edits this)
├── target/ # the artifact (agent modifies this)
├── eval/eval.sh # scoring — outputs a float (read-only)
└── results.tsv # every experiment, logged
The loop: hypothesize → implement → eval → auto-revert on regression → log → repeat until Ctrl+C.
Why opencode?
It already has all the infrastructure: file read/write permissions, git integration, the build agent, opencode run for sessions. This command wires those pieces into a reusable loop — no new dependencies, no new abstractions.
The pattern is proven at scale — Karpathy used it to autonomously improve a language model. This adapts it so any opencode user can apply it to code, config, documentation — anything with a measurable score.
Scope
~150 lines in packages/opencode/src/cli/cmd/research.ts, +2 lines in index.ts. Follows the existing effectCmd pattern (like models.ts, run.ts).
Status
PR #35495 is open and ready for review. The implementation handles scaffolding, baseline eval, --model flag, --agent flag, and auto-revert on regression. Benchmarks show the loop converges: 6584ms → 0ms across 3 iterations on a Fibonacci optimization task.
The insight
Running experiments is the core loop of software research — make a change, measure it, keep it or discard it, log it, repeat. Doing this by hand is slow and error-prone. Writing a custom shell script for each project is fragile.
This feature makes the experimental loop a first-class opencode primitive.
What it does
opencode research <goal>scaffolds a workspace and launches an autonomous agent that iterates on a code artifact:The loop: hypothesize → implement → eval → auto-revert on regression → log → repeat until Ctrl+C.
Why opencode?
It already has all the infrastructure: file read/write permissions, git integration, the
buildagent,opencode runfor sessions. This command wires those pieces into a reusable loop — no new dependencies, no new abstractions.The pattern is proven at scale — Karpathy used it to autonomously improve a language model. This adapts it so any opencode user can apply it to code, config, documentation — anything with a measurable score.
Scope
~150 lines in
packages/opencode/src/cli/cmd/research.ts, +2 lines inindex.ts. Follows the existingeffectCmdpattern (likemodels.ts,run.ts).Status
PR #35495 is open and ready for review. The implementation handles scaffolding, baseline eval,
--modelflag,--agentflag, and auto-revert on regression. Benchmarks show the loop converges: 6584ms → 0ms across 3 iterations on a Fibonacci optimization task.