BLOG
OpenResearch Teardown: Turning Claude Code into a Local-First Workspace for Research Agents
Technical Teardown: Analyzing AI Technology Frameworks—Description, Analysis, Technical Assessment, Value Judgment, and Practical Application. Author: Yongliang
On September 18, 2026, alphaXiv/OpenResearch had 4,941 stars on GitHub (as of September 18), 305 forks, 42 open issues, under the MIT license, and the repository was created on June 7, 2026—gaining nearly five thousand stars in just over two months, with a Trending #1 badge (trendshift) displayed on the README. What it does can be summed up in one sentence: instead of building a new research agent from scratch, it transforms the coding agents you are already using—Claude Code, Codex, OpenCode, Cursor—into research agents, providing them with a local-first workspace—literature reviews, hypotheses, experiments, and research reports are all versioned artifacts. This article breaks it down into six parts: what it is, how to install it, the source code trio, a calm look, is it worth it, and conclusion.
1. What is this
OpenResearch’s self-positioning is written in the first line of the README: “The local-first workspace for research agents and autoresearch”. The second line is even more straightforward—“Turn your coding agents into research agents”. Note this verb: turn, to transform, not replace. It acknowledges a reality: the reasoning and tool-calling capabilities required by research agents are already possessed by coding agents; what is missing is the structure specific to research—experiments must be reproducible, hypotheses must have lineage, evidence must remain in context, and results must be reviewable. When general coding agents start doing research directly, the most common cause of death isn’t answering questions incorrectly, but rather mixing changes from different directions in a single directory or treating a one-time successful result as a citable conclusion. This layer of structure is exactly what OpenResearch aims to fill.
The tech stack itself is an annotation of this positioning. The entire repo has 515 files; Rust accounts for 3.63MB (115 .rs files), handling the local runtime and harness management layer; TypeScript 1.38MB (89 .tsx plus 47 .ts) supports the ui/ dashboard with 254 files; JavaScript 204KB is mostly in build scripts, while Python is only 49KB with 40 files, distributed across demos and scripts. Top-level directories include ui/, src/, demo/, agent-skills/ (29 files), macos/, docs/—a structure of “local process + browser interface + skill packs + native app shell,” with the desktop end not left behind either.
The README compresses its capabilities into a six-row table: Parallel exploration (an independent agent session for each research direction, paired with an isolated git worktree); Reproducible experiments (git-native experiment tree, where every run is an immutable archive); Evidence in context; Agent selection (switch harness and model per session); Compute selection (local, own cluster, hosted); Local ownership. These six items are not a feature list, but a design manifesto—each one answers a specific failure of general coding agents when doing research. Note that the sixth item, “Local ownership,” is listed separately: artifacts and data stay in your own git repository; in this category, this is a stance, not a feature.
2. How to Install and Use
Installation is a single command:
curl -LsSf https://openresearch.sh/install.sh | shAfter installing, run orx up, and the local dashboard starts at http://127.0.0.1:4791. Subsequent operations are basically completed in the browser: starting sessions, viewing the experiment tree, and browsing evidence. The command-line tool is orx. The platform covers macOS 11+, Linux one-click, and Windows beta (requires Git for Windows)—the beta label is written as is; assess stability yourself. Also, it heavily depends on git, so confirm Git for Windows is in place on Windows first. On the model side, it can connect to LM Studio, oMLX, Ollama, or any custom OpenAI-compatible endpoint, or directly use various cloud APIs; connecting to local models means running the full process without internet access, which is a hard requirement for data-sensitive research.
Usage is divided into two layers. Manual layer: You open multiple sessions in the dashboard, each session corresponds to a research direction, each runs its own agent, each writes its own code, and you view which direction has yielded results in the tree view. The automatic layer is called Autoresearch: give an idea, and the agent walks through the loop of ‘propose idea → modify code → run experiment → view evidence → decide next step’ on its own, with multiple agents advancing in parallel, and the experiment tree ensures the lineage of every step is traceable.
On the execution side, there is a switch worth noting separately: orx up --remote user@host. The same committed code snapshot can run locally, on an SSH remote machine, Slurm cluster, K8s, Ray, HuggingFace Jobs, Modal, Tinker, or a hosted environment—the browser and data stay on your laptop, while computation is offloaded to remote GPUs. For those whose compute power isn’t fixed locally, this switch determines whether it’s a toy: the bulk of compute power in scientific research experiments lies in training, and the laptop is only good enough for viewing results.
3. Hardcore Breakdown: The Source Code Layer Trio
This is the highlight of the entire text. The README claims “local-first”, “isolation”, and “reproducibility”—claims every tool makes. Looking under the hood at the source code, three things are implemented very concretely: isolation of the experiment tree and worktree, the playbook injection mechanism, and agent-skills modularization. The line numbers are all traceable.
3.1 Experiment Tree and Worktree Isolation
The biggest risk with research agents is cross-contamination: agents working on different tasks modify code in the same directory, overwriting each other, until eventually, no one can tell which result came from which code. OpenResearch’s answer lies in ensure_session_worktree in src/local/git.rs—ensuring that every session starts with its own git worktree. The source code comment states the principle plainly: “one opencode serve child per chat session, cwd=private worktree”. One session, one agent subprocess, and the working directory is a private worktree. The two directions are isolated at the filesystem level, requiring no self-discipline from the agents.
Built atop the worktree is the experiment tree. Every experiment run corresponds to a commit on the tree—an immutable archive. Once a run ends, that specific version of the code, configuration, and inputs will never change again; subsequent comparisons are conducted against historical snapshots rather than a tangled mess of live code. The value of this design pays off the moment you write the paper: every data point can be traced back to a replayable tree. If a reviewer wants to reproduce it, they simply check out the tree and run it again. Here, git is not just an add-on for version control; it is the experimental data structure itself—this is the true weight behind the phrase “git-native”.
3.2 Playbook Injection: Swapping Brains for Every Agent
The first barrier to transforming coding agents is the system prompt. OpenResearch doesn’t require users to manually write research instructions in the configuration files of various tools; instead, it includes a built-in SYSTEM_PROMPT.md—a research playbook. When orx up is executed, this is injected into every session via each agent’s native channel. The three channels have specific locations in the source code: Claude Code uses command-line arguments, passing --append-system-prompt-file when called at src/local/claude.rs:481; Codex uses the developerInstructions field; and OpenCode uses the instructions list in the config. The same playbook, three harnesses, each feeding it in through the interface they recognize—this is the true engineering meaning of “turn your coding agents”: no hijacking, no patching, just using native mechanisms, so the agent thinks it’s simply getting to work as usual.
The playbook itself is not static text. Found at src/local/opencode.rs:179, playbook_md() replaces a batch of {token} placeholders during rendering: project facts, current status, compute defaults, and artifact paths. In other words, when a Claude Code session is launched within OpenResearch, it receives a research persona card that knows which project it’s in, where the artifacts are stored, and where to run computations by default—rather than a generic “you are a helpful assistant” prompt. Context engineering begins in the very first second of the session, saving the user from having to manually type out hundreds of words of background context every time.
3.3 agent-skills: A Research Skill Pack of 12 Modules
The second hurdle is skills. Just knowing how to chat isn’t enough; research has its own workflows: how to conduct a literature review, how to archive experiments, how to generate figures, and how to write reports. Under the agent-skills/ directory, there are 12 modules divided by workflow: orx-agent-delegation (how to delegate tasks between agents), orx-compute (compute scheduling), orx-create, orx-customize, orx-evidence (evidence management), orx-experiment-tree (experiment tree operations), orx-figures (figure generation), orx-git, orx-instances (running instance management), orx-lit-review (literature review), orx-paper (paper writing), orx-reports (report generation). Each module has a SKILL.md file, starting with four cardinal rules—first establishing the red lines for research work, before discussing how to get the work done. Within a session, they are loaded on demand via orx skill <name>, retrieving only what is used, not stuffing everything into the context at once.
The picture formed by this trio is: worktree isolation ensures physical separation, playbook injection ensures every session follows research protocols from the very first second, and the 12 skill modules ensure the agent knows how to handle literature reviews and experiment archiving respectively. The harness management layer is under src/local/harness/, consisting of six files: claude.rs, codex.rs, cursor.rs, opencode.rs, opencode_v2.rs, and detect.rs, all managed uniformly by AgentHost (a local service based on axum)—multi-agent parallelism isn’t about multiple processes running chaotically, but a local host handling unified scheduling, where detect is responsible for identifying which available harnesses are installed on the machine. Writing this layer in Rust is a reasonable choice: the host process needs to stay alive for a long time while managing multiple child processes simultaneously, making both memory safety and concurrency models applicable.
4. A Calm Look
First, let’s clarify the metrics. 4,941 stars is the achievement of over two months, and the README displays a Trending #1 badge; this is a factual statement. However, the rate of star growth and whether the tool is usable are two different matters. For a project just two months old, with 42 open issues sitting there, and interfaces and commands within 515 files still in flux, the integration method written today might change tomorrow. The MIT license does cover the worst-case scenario: even if the project stops updating, the version in hand can still be used.
Second, “local-first” is both a strength and a boundary. Artifacts, evidence, and code are all in the local git repository; ownership is clear, it runs offline, and data doesn’t leave the machine when connecting to local models. These are hard requirements for those handling unpublished data and unpublished results; work prior to submission shouldn’t be on the cloud in the first place. Conversely, it currently lacks a centralized sharing layer: team collaboration, result publishing, and cross-machine synchronization all rely on you piecing together existing git mechanisms yourself; the tool doesn’t do it for you. People accustomed to GitHub-style collaboration will feel something is missing here.
Third, Autoresearch’s autonomy should be read as advertised. The README describes it as “propose idea → modify code → run experiment → view evidence → determine next step”. The direction is credible, but the quality of each loop depends on the model you connect and the compute power you provide. The cost of the agent choosing the wrong direction is burning up the compute power of an entire experimental tree. You can use it as an automated research assistant, but you cannot use it as a researcher capable of independently producing conclusions—at least not yet.
Fourth, Windows is still in beta. People whose main development machines are Mac or Linux won’t feel the difference, but Windows users should first consider clearly whether they can accept the git environment and the beta status.
V. Is It Worth It
Categorized by audience. For those working on ML, systems, or any research direction that requires running experiments, and are already using Claude Code or OpenCode, this is the smoothest onboarding path: no need to migrate tools or change habits. After orx up, your original agent gains a research skeleton—experiment trees, worktree isolation, playbooks, and skill packs are all ready-made, so the learning curve is almost zero. For those who need to run models locally (due to data sensitivity or budget constraints), direct connections to LM Studio, oMLX, and Ollama ensure complete compute sovereignty. For those with remote compute resources, the single command orx up --remote offloads the computation while keeping the browser and artifacts locally; this setup is much healthier than straining a laptop.
The scenarios where you should hold off are also clear: if you aren’t doing experimental research and just need to read papers and take notes, you won’t use most of the 12 skill modules. It would be overkill; a handy note-taking workflow is sufficient. If you have heavy team collaboration needs and require centralized result management, the local-first architecture runs counter to your requirements. If you expect an “agent to automatically write a paper for me,” Autoresearch is a process assistant, not a ghostwriter; you will be disappointed if your expectations are wrong. Additionally, the MIT license and local execution make the cost of trial and error very low—just install it, pick a small reproduction task, and run through the process. You’ll know within half a day if it suits you. This is the most cost-effective way to try out this kind of tool.
Conclusion
OpenResearch answers a question that has been avoided for a long time: must research agents be built from scratch? Its answer is no—the reasoning and tool capabilities of Claude Code, Codex, OpenCode, and Cursor are already sufficient; what is missing is the structure of research, and structure can be supplemented through engineering. This judgment is implemented very concretely in the source code: ensure_session_worktree gives each session a private worktree; a SYSTEM_PROMPT.md is injected into each session via three native channels: --append-system-prompt-file (claude.rs:481), developerInstructions, and config instructions; playbook_md() fills in project facts and compute defaults during rendering; 12 agent-skills modules are loaded on demand via orx skill; and the harness layer is uniformly scheduled by AgentHost. The experiment tree grows on git, each run is an immutable archive, and reproducibility changes from a promise into a data structure. For those currently using coding agents for research, this is currently the most complete “retrofit rather than rebuild” solution; for those researching agent engineering, it demonstrates how to bring “local-first” from slogan to line number.
Reference Sources
- alphaXiv/OpenResearch README (GitHub; positioning, installation, table of six capabilities, Autoresearch, runtime)
- OpenResearch source code (local clone): src/local/git.rs (ensure_session_worktree), src/local/claude.rs:481 (—append-system-prompt-file), src/local/opencode.rs:179 (playbook_md), src/local/harness/ (claude.rs / codex.rs / cursor.rs / opencode.rs / opencode_v2.rs / detect.rs), agent-skills/ (12 SKILL.md files)
- Repository data: 4,941★, fork 305, issues 42, MIT, created on 2026-06-07 (as of 2026-09-18)