ResearchClaw#

AutoResearchClaw is a fully autonomous 23-stage research pipeline that transforms a single research idea into a conference-ready academic paper with real literature from OpenAlex, Semantic Scholar, and arXiv.

Quick Start#

Basic Usage#

User says: "Research [topic]"

Agent workflow:

1. Check if AutoResearchClaw is installed ( which researchclaw)
2. If not installed: clone, setup venv, install with pip install -e .
3. Copy config.researchclaw.example.yaml → config.arc.yaml
4. Ask user for LLM provider choice (OpenAI-compatible or ACP agent)
5. Configure with API keys or ACP agent selection
6. Run: researchclaw run --topic "[topic]" --auto-approve
7. Monitor progress, return results from artifacts/rc-*/deliverables/

Configuration#

Ask user for LLM backend preference:

Option 1: OpenAI-compatible API

yaml

llm:
  provider: "openai-compatible"
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"  # or ask for key
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

Option 2: ACP Agent (Claude Code, Codex, Gemini)

yaml

llm:
  provider: "acp"
  acp:
    agent: "claude"  # or "codex", "gemini", etc.
    cwd: "."

Installation#

Check Installation#

bash

which researchclaw || echo "Not installed"

Install AutoResearchClaw#

bash

cd ~
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify Installation#

bash

researchclaw --version

Running Research#

Basic Command#

bash

researchclaw run --topic "Your research idea" --auto-approve

With Specific Config#

bash

researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

Output Location#

Results in: ~/AutoResearchClaw/artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/

Deliverables#

After completion, the agent should:

1. Check deliverables/ directory contents
2. Present key outputs:
   • paper.tex - Conference-ready LaTeX
   • paper_draft.md - Markdown paper
   • references.bib - Real citations
   • verification_report.json - Citation integrity check
   • runs/ - Experimental code and results
   • charts/ - Generated figures
   • reviews.md - Multi-agent peer review
3. Copy/present relevant sections to user

Pipeline Stages (23 Total)#

Phase A: Research Scoping#

• Stage 1: TOPIC_INIT
• Stage 2: PROBLEM_DECOMPOSE

Phase B: Literature Discovery#

• Stage 3: SEARCH_STRATEGY
• Stage 4: LITERATURE_COLLECT
• Stage 5: LITERATURE_SCREEN [gate]
• Stage 6: KNOWLEDGE_EXTRACT

Phase C: Knowledge Synthesis#

• Stage 7: SYNTHESIS
• Stage 8: HYPOTHESIS_GEN

Phase D: Experiment Design#

• Stage 9: EXPERIMENT_DESIGN [gate]
• Stage 10: CODE_GENERATION
• Stage 11: RESOURCE_PLANNING

Phase E: Experiment Execution#

• Stage 12: EXPERIMENT_RUN
• Stage 13: ITERATIVE_REFINE
• Stage 14: RESULT_ANALYSIS
• Stage 15: RESEARCH_DECISION

Phase F: Analysis & Decision#

• Stage 16: PAPER_OUTLINE
• Stage 17: PAPER_DRAFT
• Stage 18: PEER_REVIEW
• Stage 19: PAPER_REVISION

Phase G: Paper Writing#

• Stage 20: QUALITY_GATE [gate]
• Stage 21: KNOWLEDGE_ARCHIVE
• Stage 22: EXPORT_PUBLISH
• Stage 23: CITATION_VERIFY

Hardware Awareness#

AutoResearchClaw auto-detects:

• NVIDIA CUDA (GPU)
• Apple MPS (M1/M2/M3)
• CPU-only fallback

Adapts code generation, imports, and experiment scale accordingly.

Quality Features#

• Real Citations: OpenAlex, Semantic Scholar, arXiv - no hallucinated references
• 4-Layer Verification: arXiv ID → CrossRef DOI → Semantic Scholar → LLM relevance
• Multi-Agent Debate: Hypothesis generation, result analysis, peer review
• Self-Healing: NaN/Inf detection, automatic code repair
• Conference Templates: NeurIPS, ICLR, ICML support

OpenClaw Bridge Integration (Optional)#

Enable in config.arc.yaml:

yaml

openclaw_bridge:
  use_cron: true          # Scheduled research runs
  use_message: true       # Progress notifications (Discord/Slack/Telegram)
  use_memory: true        # Cross-session knowledge persistence
  use_sessions_spawn: true # Parallel sub-sessions
  use_web_fetch: true     # Live web search during literature review
  use_browser: false      # Browser-based paper collection

MetaClaw Integration (Optional)#

For cross-run learning:

yaml

metaclaw_bridge:
  enabled: true
  skills_dir: "~/.metaclaw/skills"
  lesson_to_skill:
    enabled: true
    min_severity: "warning"
    max_skills_per_run: 5

Troubleshooting#

Installation Issues#

bash

# Check Python version
python3 --version  # Requires 3.8+

# Install dependencies
pip install -r requirements.txt

LLM API Errors#

• Verify OPENAI_API_KEY is set
• Check API endpoint is accessible
• Fallback models configured correctly

Sandbox Issues#

• Ensure Python path is correct: .venv/bin/python
• Check allowed imports in config
• Adjust memory limits if needed

Literature Collection Failures#

• Check internet connectivity
• Semantic Scholar API key optional (higher rate limits)
• OpenAlex should work without API key

Advanced Usage#

Specify Research Domains#

bash

researchclaw run --topic "Your topic" --domains ml,nlp --auto-approve

Target Specific Conference#

yaml

export:
  target_conference: "neurips_2025"  # neurips_2025 | iclr_2026 | icml_2026

Custom Prompts#

yaml

prompts:
  custom_file: "custom_prompts.yaml"

Resources#

• GitHub: https://github.com/aiming-lab/AutoResearchClaw
• Integration Guide: See AutoResearchClaw docs/integration-guide.md
• Testing Guide: See AutoResearchClaw docs/TESTER_GUIDE.md
• Discord: https://discord.gg/u4ksqW5P

Comparison with Superpowers#

• ResearchClaw: Academic research, literature review, paper writing, experimental validation
• Superpowers: Software development, TDD, code review, production code

Use ResearchClaw for research/paper generation. Use Superpowers for production software implementation. They complement each other when researching then implementing findings.