Why OpenResearch Treats Research as a Reproducibility Problem
OpenResearch is an open-source Rust CLI and local dashboard for research agents and autoresearch. This opening chapter asks a practical question about the product: how can an agent move quickly from an idea to a code change without making the resulting experiment impossible to interpret? The answer is not simply “use a better model.” OpenResearch links local ownership, Git branches, run contracts, immutable source snapshots, supervised logs, and durable artifacts so that a reader can follow what changed, what ran, and what the evidence actually supports.
That makes OpenResearch more interesting than a dashboard wrapped around a coding assistant. Its central design problem is the gap between producing a result and being able to trust the path by which the result was produced. An agent can generate a plausible hypothesis, edit a repository, launch a job, and summarize the outcome in minutes. But speed also makes it easy to lose the starting point, mix changes, compare unlike runs, or let a polished report outrun the underlying measurement. OpenResearch treats those risks as system-boundary problems: each stage needs an owner, a durable record, and a transition that can be inspected later.
The problem is not speed; it is attribution
Agent-assisted research changes the bottleneck. In a conventional experiment, a person may spend much of their time writing code, preparing a run, checking logs, and assembling a report. A tool-using agent can compress those actions, and OpenResearch is designed to let several research directions proceed in parallel. The benefit is real: more hypotheses can be explored, and routine operations need not consume the researcher's attention.
The corresponding danger is not that an agent makes a mistake—people and scripts do that too. The danger is that the workflow makes a mistake difficult to locate. If an agent edits a shared checkout while another agent changes the same files, which version produced the result? If a run uses uncommitted files, a later reader cannot reconstruct the source from the visible branch. If a dashboard says that a job finished but the log does not contain the effective configuration or final metric, “finished” describes execution state, not research evidence. If a report states that one variant won, but the next variant resets to the original baseline, the apparent progress may be a sequence of disconnected comparisons.
OpenResearch's answer is to make lineage part of the working surface. A project gives the work a durable home. An experiment is attached to a parent and a Git branch. A fixed run command defines how the branch is evaluated. A submitted run is tied to a recorded commit rather than a moving worktree. Logs and result records remain available for inspection. The next hypothesis is supposed to descend from what was learned, rather than merely being another child of the starting point. None of this guarantees that a hypothesis is good or that a metric is scientifically sufficient. It does make the path to a claim more legible.
This distinction matters because reproducibility has several layers. At the narrowest layer, a system should identify the source that ran. At the operational layer, it should preserve the command, state transitions, output, and failure information. At the scientific layer, a researcher must still decide whether the data, metric, controls, and interpretation are appropriate. OpenResearch is strongest in the first two layers. It supplies structure around the third; it does not replace domain judgment.
A local control plane with explicit crossings
The product's local-first identity is concrete. The normal orx up mode binds the dashboard to the loopback address on the machine running it, serves a local web interface and JSON API, and stores project, conversation, experiment, run, log, code, and artifact state locally. A local SQLite store and local files form the control plane. The dashboard is a view into that state, not a separate cloud record that must become authoritative before the work exists.
That ownership boundary has practical consequences. A researcher can keep a repository and its experiment history on their machine, use a coding-agent session in a private worktree, and inspect run logs through the same local interface. The product also supports optional GitHub publication, but publication is not required to transport code to compute. The local repository and its recorded branches remain the history used to define experiments.
“Local-first” does not mean “offline.” Literature discovery and paper retrieval can call public services. GitHub operations and connected tools can use the network. A selected compute backend may receive a source snapshot, and managed compute requires an account or organization capability. Even local inference has a network boundary if the researcher is downloading models, searching papers, or using remote tools. The useful claim is therefore about ownership and control: the main research record is local by default, while crossings are explicit and consequential.
The agent relationship follows the same pattern. OpenResearch can work with several coding-agent harnesses, and OpenCode sessions receive project context through a generated playbook. A session runs in a private Git worktree rather than editing the same checkout as every other session. Worktrees share repository history and references, so a branch created in one session can be discovered by another; Git still prevents two worktrees from claiming the same branch at once. This is a careful compromise. Isolation protects the unit of editing, while shared history preserves the fact that the project is one research space rather than a collection of invisible copies.
A local model can change where inference happens without changing that control model. OpenResearch documents connections to local servers such as LM Studio, oMLX, Ollama, and other OpenAI-compatible endpoints. Those connections are saved in the local data directory, and existing provider settings remain available. But model locality does not turn an agent's decisions into evidence. A small or poorly configured model may mishandle tools or context; a local server may fail; and the commands, literature searches, or compute requests made by the agent may still reach other systems. The model is one participant in the workflow, not the source of truth for the workflow.
The diagram's most important arrow is the one that crosses out of the local control plane and returns with evidence. OpenResearch can send work to local, user-owned, scheduled, serverless, or managed compute, but the launch remains attached to a local experiment record. That arrangement is what lets remote power coexist with local ownership. It is also where the remaining limits begin: the source snapshot can be fixed while the operating environment, data, provider capacity, and external services still vary.
The chain from idea to inspectable result
The chain begins before an experiment exists. A local project records the repository path, baseline branch, optional run command, and possibly paper context. Creating a project does not automatically make a result; the experiment tree starts empty, and the first no-parent experiment becomes the baseline. This separation is important. A repository is a body of source code. A project is the local container that gives that source a research identity and a place for later runs and artifacts.
An experiment then expresses a question in lineage. A root branches from the project baseline; a child branches from the parent's tip and inherits the run command unless deliberately changed before the workflow is established. The intended tree is not a flat sweep of unrelated variants. Options for one decision are siblings. Once a run answers a node, the node is frozen; a later idea becomes a child of the confirmed winner. A failed run that answered nothing is repaired on its provisional branch rather than being misrepresented as a new scientific hypothesis.
At launch, the branch's recorded commit is more important than the agent's current checkout. OpenResearch archives that commit, computes a content digest, and gives the selected backend an immutable source payload. The local runner extracts the payload into an isolated run directory, and remote adapters transport and extract the same kind of snapshot before executing the fixed command. Uncommitted worktree files are excluded. This does not capture every condition that can affect a result—package state, data versions, random seeds, hardware behavior, and external responses still matter—but it answers a foundational question: which source did the run receive?
Execution state is then recorded separately from interpretation. A run moves through starting and running states to a terminal outcome such as done, failed, or cancelled. A detached supervisor can continue watching after the initiating command or dashboard turn ends, and OpenResearch can reattach supervision when the local service starts again. A run log is the evidence channel: it needs the effective configuration, final metrics, a compact summary, and enough trajectory to make a later judgment possible. A status badge that says “done” cannot establish that the metric was appropriate, that the data were clean, or that a claimed improvement generalizes.
Finally, evidence must change what happens next. The intended autoresearch loop forms a small round of co-equal hypotheses, commits each branch, launches through the common runner, returns to the first completion, rereads the run states, and inspects logs and diffs. The result can justify repair, refill, promotion, or stopping. Promoting a winner gives the next round a meaningful parent; stopping after repeated non-answers or regressions protects both budget and interpretation. Literature search can supply context for the question, and reports, figures, data, or PDFs can preserve the outcome, but neither discovery snippets nor polished artifacts can repair a missing measurement.
That is the reproducibility problem OpenResearch is actually addressing. It is not promising that agents will discover important truths automatically. It is building a local control plane in which a researcher's claim can be connected to a project, a branch, a recorded source, a compute event, a log, and an artifact—and in which the gaps between those records remain visible. The next question is therefore not how to launch the most experiments. It is what the project must own before an experiment can be compared at all.