ResearchClaw: a local-first runtime for research state, claims and evidence
ResearchClaw is a personal AI assistant built for research: fast to set up, easy to run locally or in the cloud, and ready to integrate with the chat apps you already use. With extensible skills, it helps you streamline literature review, note-taking, experiment tracking, and paper writing—end to end.
At a glance
- What is it?
- ResearchClaw is an Alpha-stage Python project that keeps projects, workflows, tasks, claims, evidence and experiments in one local runtime with a web console, channels and automation. The design is coherent, but the README itself names evidence-matrix quality and claim-evidence validation as the biggest remaining gaps.
- Who is it for?
- Adopt ResearchClaw if you already run Python 3.10+ locally and want one place to hold project, workflow, claim, evidence and experiment state instead of chat threads and shell history. Do not adopt it if you need a stable data model or validated claim-evidence checking, because the README calls both out as open gaps.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 165 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem ResearchClaw targets: research state that evaporates between sessions
The README opens with a list of failure modes it wants to replace: work disappearing into one-off chats or shell history, and search, execution, writing and follow-up being split across separate tools. The stated fix is persistence of a `project -> workflow -> task -> artifact` chain, with notes, claims, evidence, drafts and reminders attached to it. That is a narrower and more concrete goal than "AI assistant for research". The unit of value is not a better answer in a chat window. It is a record that survives the chat window.
The intended user is a researcher who already works in Python and is willing to run a service locally. The README describes a workspace created under `~/.researchclaw` with bootstrap Markdown files including `SOUL.md`, `AGENTS.md`, `PROFILE.md` and `HEARTBEAT.md`, which implies the assistant's behaviour is configured by editing files on disk rather than through a hosted settings page. Anyone who wants a zero-install web product is not the audience here. The project positions itself as the "runtime and workspace layer" of a larger Research-Equality stack, with sibling repositories covering idea generation, literature discovery, research design, experiments and paper writing. ResearchClaw is the piece that holds state while those skills do the stage-specific work.
What the runtime actually consists of
The README describes a long-running app runtime with control-plane APIs, a web console, multi-agent routing with per-agent workspaces and binding rules, and a persistent research state layer. The console is a frontend served by the backend: the README states that the backend automatically serves `console/dist` when it exists, and that if the page reports `Console not found` you build the frontend once with `npm install` and `npm run build` inside `console`. That is a two-language deployment, Python for the service and Node for the UI, and it is worth knowing before you start.
Channels are a first-class concept. The README lists built-in channels for `console`, `telegram`, `discord`, `dingtalk`, `feishu`, `imessage`, `qq` and `voice`, and claims the same research state is exposed through the web console, IM channels, cron jobs, sessions and control-plane APIs. Model management is similarly plural: multiple providers, multiple models per provider, and fallback chains. Provider types listed in the code today are `openai`, `anthropic`, `gemini`, `ollama`, `dashscope`, `deepseek`, `minimax`, `other` and `custom`. The presence of `ollama` in that list is consistent with the local-first framing, though the README does not state which features work with a local model and which assume a hosted one.
Extensibility is standardized around `SKILL.md`, with Skills Hub search and install APIs, MCP client management, and custom channels. The README also mentions automation triggers, cron jobs, heartbeat, proactive reminders and runtime observability. The `HEARTBEAT.md` bootstrap file suggests the heartbeat is configured in Markdown rather than in a YAML or TOML config, which is a deliberate choice and an unusual one.
Getting it running: the four commands the README gives
The quick start is short. Clone the repository, then `pip install -e .` from the project root. Initialize the workspace with `researchclaw init --defaults --accept-security`, which creates the working directory `~/.researchclaw`, the secret directory `~/.researchclaw.secret`, and the bootstrap Markdown files. The `--accept-security` flag is not explained in the README beyond its presence in the command, so read what it accepts before running it on a machine that holds anything you care about.
Model configuration is either interactive or a single command. The README gives `researchclaw models config` for the guided path, and `researchclaw models add openai --type openai --model gpt-5 --api-key sk-...` for the direct path. Note the shape: a provider name, a `--type` drawn from the supported list, a `--model`, and an API key on the command line. Passing a key as a flag means it can land in shell history; the secret directory exists, but the README does not say whether `models add` writes the key there or into the working directory.
Start the service with `researchclaw app --host 127.0.0.1 --port 8088` and open `http://127.0.0.1:8088`. The default host is loopback, which is the right default for a tool that holds research notes and provider keys. If you change it to a public interface, the README offers no authentication guidance, and the presence of IM channels such as `telegram` and `discord` means the runtime is designed to be reachable by external services anyway.
The Research page and the claim-evidence model
The part of the console the README emphasizes is the Research page. After startup you can create a project, inspect workflows, claims and reminders, view execution health and recent blockers, and dispatch, execute or resume remediation work. The README states the code includes a minimal research workflow runtime, a claim/evidence graph, experiment tracking, blocker remediation and a project dashboard.
The claim/evidence graph is the most interesting design decision in the project. Instead of treating a paper draft as a document, it treats the assertions inside it as objects that link to supporting evidence, which is what makes "blocker remediation" meaningful: a claim without evidence is a blocker that can be dispatched as work. That is a real mechanism, not a marketing phrase.
It is also the least finished part. The README says plainly that the biggest remaining gaps are evidence-matrix quality, stronger claim-evidence validation, richer external execution adapters, and submission and reproducibility packaging. Read that sentence twice before building a workflow on top of the graph. The structure exists; the checking that would make the structure trustworthy does not, by the project's own account. A claim-evidence graph that accepts weak links is worse than no graph if you rely on it to tell you what is unsupported.
Where ResearchClaw is the wrong tool
The README labels the project Alpha in the badge and in the prose, and says it is "no longer just a platform shell". That phrasing is honest and also a warning. If your requirement is a stable schema for research state that other systems can depend on, this is not it yet. The gaps listed above touch the data model's core, not its edges.
The second limitation is scope. ResearchClaw is the runtime, and the README is explicit that stage-specific work lives in companion repositories such as RE-literature-discovery and RE-paper-writing. Installing ResearchClaw alone gives you a workspace and a set of built-in tools (paper search and download, BibTeX utilities, LaTeX helpers, data analysis, browser and file tools), but the authoritative skills for literature ranking, research design and experiment validation are elsewhere. A single-repository install will feel thinner than the README's ecosystem table suggests.
The third is operational. This is a long-running service with a separately built frontend, a secret directory, multiple IM channel integrations and cron automation. That is a real deployment surface for a personal tool. If you wanted a script you run once, the runtime is overhead you will pay for on every upgrade.
How it differs from a general agent framework
The obvious comparison is a general-purpose agent framework such as LangGraph or CrewAI. Those give you orchestration primitives, and you bring your own persistence, your own console and your own channel integrations. ResearchClaw inverts that: persistence, console, channels, provider routing and fallback chains are in the box, and the research domain shapes the data model through projects, workflows, claims, evidence, experiments and artifacts.
The practical difference shows up in what you write. With a general framework you write the state layer and then the research logic. With ResearchClaw you write `SKILL.md` files and MCP integrations and let the runtime hold the state. The trade is control. A general framework lets you define exactly how a claim links to evidence; ResearchClaw defines that for you, and the README says that definition is still being tightened.
Compared with a plain note-taking setup, the difference is the execution loop. Notes record; ResearchClaw records and then dispatches remediation work against what it recorded. That loop is the whole argument for running a service instead of keeping a folder of Markdown files, and it is also the part that depends most on the unfinished validation.
Maintenance cost and the licence question
The repository metadata reports the licence as NOASSERTION, while the README badge links to Apache 2.0 and points at a `LICENSE` file. Those two signals disagree, and the disagreement matters for anyone planning to build on the code. Read the actual `LICENSE` file in the repository before you depend on a particular set of permissions. This is not legal advice; it is a note that the machine-readable and human-readable licence claims do not match in the material available.
On maintenance, the project is active: the last push recorded is 2026-04-04, with releases labelled "Product (V1.0)" on 2026-03-04 and "Pto (V1.1)" on 2026-03-07. The release naming is inconsistent ("Pto" looks like a typo for a version codename), which is a small signal about release hygiene. Upgrading means re-running `pip install -e .` for the Python side and rebuilding `console/dist` for the frontend, since the backend serves a prebuilt bundle. Any change to the research state schema is the upgrade risk to watch, because the README's own gap list says that schema is still moving.
The bootstrap files under `~/.researchclaw` are yours to edit, so customization cost is low and portable. The cost that is not low is attention: an Alpha runtime with cron jobs, heartbeat reminders and IM channels generates state you then have to read. Set the heartbeat and reminder behaviour deliberately rather than accepting defaults you have not inspected.
Editorial conclusion
Adopt ResearchClaw if you already run Python 3.10+ locally and want one place to hold project, workflow, claim, evidence and experiment state instead of chat threads and shell history. Do not adopt it if you need a stable data model or validated claim-evidence checking, because the README calls both out as open gaps. Before committing, run `researchclaw init --defaults --accept-security`, check what it writes to `~/.researchclaw` and `~/.researchclaw.secret`, and confirm the actual licence text, since the repository metadata reports NOASSERTION while the README badge points at Apache 2.0.
Community notes