AutoResearchClaw - Moses Yebei

The Problem

Researchers face a long, tedious pipeline between having an idea and producing a paper: literature review, hypothesis formulation, experiment design, code execution, statistical analysis, and writing. Each step requires different tools and expertise, and the process is rarely reproducible or automated. AutoResearchClaw attempts to collapse this into a single conversational interaction.

What This Does

AutoResearchClaw is a Python-based system that orchestrates a multi-stage research pipeline—from literature search through paper writing—with optional human-in-the-loop guidance. The researchclaw/ directory (354 files) contains the core orchestration, with researchclaw/cli.py and researchclaw/__main__.py as entry points. The system claims to be "self-evolving," using .claude/skills/a-evolve/SKILL.md to improve its own prompts based on outcomes.

The project ships with domain-specific Docker images (researchclaw/docker/Dockerfile.biology, .chemistry, .economics, .math, .generic) for isolated experiment execution. It also includes an MCP server (researchclaw/mcp/server.py) for integration with Claude or other MCP-compatible clients. The experiments/ directory (176 files) contains the actual research code templates.

How It Is Wired

Execution starts at researchclaw/__main__.py, which routes to researchclaw/cli.py. The CLI parses a research idea and initializes the pipeline. The pipeline is documented in RESEARCHCLAW_AGENTS.md and consists of stages (literature search → hypothesis → experiment → analysis → writing). Each stage is driven by an agent defined in config.researchclaw.example.yaml.

The system's control flow is not fully mapped from the provided file structure—the internal call graph, entry points, and external touchpoints beyond the CLI and MCP server are not documented in the analysis blocks. The researchclaw/docker/ Dockerfiles suggest experiments run in isolated containers, but the exact code that spawns them is not visible in the file listing.

Key files by responsibility:

researchclaw/cli.py — command-line entry, orchestrates the pipeline
researchclaw/mcp/server.py — MCP interface for external AI clients
config.researchclaw.example.yaml — agent and pipeline configuration (no .env or key files found)
.claude/skills/*/SKILL.md — prompt templates for each research stage
frontend-legacy/ — an older React/Flask interface, likely superseded by the MCP integration

How To Use It

Setup: Install Python dependencies from pyproject.toml (pip or uv). No lockfile exists, so builds are not fully reproducible. The frontend-legacy/package.json is a legacy dependency, not the primary path.

Configuration: Copy config.researchclaw.example.yaml to a working config and adjust agent settings. No API keys or environment variables are documented in the file structure.

Running it: The README's primary path is via OpenClaw/MCP integration. The CLI entry point is:

python -m researchclaw "Your research idea here"

The exact flags and options are not documented in the analysis; the README excerpt focuses on the conversational interface. Docker images are built per-domain from the Dockerfile.* files.

Real-World Use

A biology researcher wants to test a hypothesis about gene expression. They connect Claude (via the MCP server) to AutoResearchClaw, describe the idea, and the system: (1) runs a literature search, (2) formulates a hypothesis, (3) spawns a container from Dockerfile.biology to run Biopython-based experiments, (4) analyzes results with statistical reporting, and (5) writes a draft paper. The human reviews at checkpoints defined in docs/HITL_GUIDE.md.

Code Health & Issues

Static analysis has not been run on this repository—no MEASURED ANALYSIS block is present. The following are inferred from the file structure:

Med/SDLC - No CI/CD pipeline detected (no .github/ or CI config) - automated testing is not gated
Low/Risk - frontend-legacy/package.json has no lockfile - non-reproducible frontend builds
Low/Docs - 108 test files exist but no test runner config or coverage report is visible; the README claims 2699 tests passed, which is unverifiable from structure alone

The Bottom Line

The architecture is ambitious—a multi-agent, container-isolated research pipeline with MCP integration is a credible design. The lack of CI, lockfiles, and visible internal wiring docs makes it risky to adopt as-is. Best suited for a research lab willing to invest in hardening the pipeline and adding their own test/CI infrastructure.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

756 files

Python403
YAML97
Markdown95
JSON82
Shell10
JavaScript10

ReactFlaskExpressDockerTransformers

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["researchclaw 275 modules"] g1["tests 101 modules"] g2["experiments 21 modules"] g3["frontend-legacy 10 modules"] g4["scripts 5 modules"] g1 -->|357| g0 g4 -->|12| g0 g2 -->|3| g0

Module dependencies

The 10 most depended-upon modules of 413, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_researchclaw_config["config"] n1_researchclaw_llm_client["client"] n2_researchclaw_pipeline_stages["stages"] n3_esearchclaw_prompts___init__["__init__"] n4_researchclaw_adapters["adapters"] n5_hclaw_domains_prompt_adapter["prompt_adapter"] n6_earchclaw_experiment_sandbox["sandbox"] n7_searchclaw_pipeline_executor["executor"] n8_searchclaw_hitl_intervention["intervention"] n9_esearchclaw_domains_detector["detector"] n5_hclaw_domains_prompt_adapter --> n9_esearchclaw_domains_detector n6_earchclaw_experiment_sandbox --> n0_researchclaw_config n7_searchclaw_pipeline_executor --> n4_researchclaw_adapters n7_searchclaw_pipeline_executor --> n0_researchclaw_config n7_searchclaw_pipeline_executor --> n1_researchclaw_llm_client n7_searchclaw_pipeline_executor --> n3_esearchclaw_prompts___init__ n7_searchclaw_pipeline_executor --> n2_researchclaw_pipeline_stages n7_searchclaw_pipeline_executor --> n8_searchclaw_hitl_intervention classDef cyc stroke:#ef4444,stroke-width:2px; class n0_researchclaw_config,n1_researchclaw_llm_client,n3_esearchclaw_prompts___init__,n5_hclaw_domains_prompt_adapter,n7_searchclaw_pipeline_executor cyc;

Dependencies

3 of 4 declared dependencies are a major version behind. Resolved 4 of 4 against the registry.

Package	Declared	Latest	Behind
`rich`	>=13.0	15.0.0	2 major
`arxiv`	>=2.1	4.0.1	2 major
`numpy`	>=1.24	2.5.2	1 major

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
LowDependencies declared without a lockfile - non-reproducible builds frontend-legacy/package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

Commit a lockfile beside the manifesthigh

frontend-legacy/package.json

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Add a workflow that builds and tests this repositoryhigh

413 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh

researchclaw/docker/Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

researchclaw/docker/Dockerfile

nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Move large binaries to Git LFS or out of the repositorymedium

website/assets/framework.png

1 blobs over 5MB: framework.png 5.6MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.