openlair/dr-claw

English | 中文

Table of Contents

• Overview
• What’s New
• Highlights
• Quick Start
• Configuration
• OpenClaw Integration
• Research Lab - Quick Example
• Usage Guide
• Claude Code Plugin
• Additional Details
• Contributing
• FAQ
• License
• Citation
• Acknowledgments
• Support & Community

Overview

Dr. Claw is a general-purpose AI research assistant designed to help researchers and builders execute end-to-end projects across different domains. From shaping an initial idea to running experiments and preparing publication-ready outputs, Dr. Claw keeps the full workflow in one place so teams can focus on research quality and iteration speed.

Product Screenshot

What’s New

• 🧪 Auto Research Hub 2026-04-08 — One click to launch fully autonomous research! Pick a tool pack (ARIS, Autoresearch, DeepScientist), hit configure, choose a workflow in Chat — and watch the agent run your entire research pipeline from idea to paper while you sleep.
• 🖥️ Desktop App & npx 2026-04-06 — Dr. Claw now runs as a native desktop app! Grab the .dmg / .exe from GitHub Releases, or run npx dr-claw for zero-setup instant start.
• 🗂️ Multi-Tab Sidebar 2026-04-06 — Research Lab and Files now live side-by-side as switchable tabs in the right sidebar — everything you need, one glance away.
• 📂 File Preview Overlay 2026-04-06 — Preview any project file inline with a sleek pill toggle and sidebar browser — no more context-switching!
• 💬 Terminal Chat 2026-04-06 — Love the terminal? Run dr-claw chat for a fully agentic session with any OpenRouter model — zero browser required.
• 🎛️ Reasoning Controls 2026-03-30 — Fine-tune your AI’s thinking! Codex reasoning effort and Gemini thinking strength selectors are now right in Chat.
• 🖥️ Local GPU Detection 2026-03-30 — Dr. Claw automatically detects your local GPU resources — ready to put that hardware to work.
• 🌐 OpenRouter Provider 2026-03-28 — Unlock hundreds of models (GPT-5, Claude, Gemini, DeepSeek, Llama, Kimi, and more) with a single API key. The world’s models at your fingertips!
• 🔄 Session Recovery 2026-03-26 — Crashed mid-session? No sweat — hit the retry button and pick up right where you left off.

Highlights

• 🔬 Research Lab — Structured dashboard for end-to-end research: define your brief, generate a pipeline of tasks, track progress across Survey → Ideation → Experiment → Publication → Promotion, and inspect source papers, ideas (rendered with LaTeX math), and cache artifacts — all at a glance
• ⚡ Auto Research — Start one-click sequential task execution directly from the Project Dashboard, open the generated session live, and receive an email when the run completes
• 📚 100+ Research Skills — A curated library spanning idea generation, code survey, experiment development & analysis, paper writing, review response, and delivery — automatically discovered by agents and applied as task-level assistance
• 🗂️ Chat-Driven Pipeline — Describe your research idea in Chat; the agent uses the inno-pipeline-planner skill to interactively generate a structured research brief and task list — no manual templates needed
• 🤖 Multi-Agent Backend — Seamlessly switch between Claude Code, Gemini CLI, Codex, and OpenRouter as your execution engines

What the Pipeline Produces

See docs/pipeline-outputs.md for the full artifact list and project directory structure.

Feature Gallery

Quick Start

Desktop App (Beta): Want to skip the setup below? Download the latest .dmg (macOS) or .exe (Windows) installer from GitHub Releases and run it directly. The desktop app is currently in beta — for a more stable experience, follow the full installation steps below.

Prerequisites

• Node.js v20 or higher (v22 LTS recommended, see .nvmrc)
• At least one of the following CLI tools installed and configured:
  • Claude Code CLI
  • Gemini CLI
  • Codex CLI
• Some systems need native build tools for dependencies like node-pty and better-sqlite3. If npm install fails, see FAQ.

Cursor agent support is in progress and coming soon.

Option 1: Run with npx (Recommended)

No cloning or manual setup required — just run:

npx dr-claw

Or install globally for repeated use:

npm install -g dr-claw
dr-claw

Then open your browser at http://localhost:3001 to create your account and start using Dr. Claw.

Option 2: Install from Source (For Development)

1. Clone the repository:

git clone https://github.com/OpenLAIR/dr-claw.git
cd dr-claw

2. Install dependencies:

npm install

3. Configure environment:

cp .env.example .env
# Edit .env with your preferred settings (port, etc.)

Need custom ports, auth, or workspace settings? See docs/configuration.md.

4. Start the application:

# Development mode (with hot reload)
npm run dev

Then create your account via the browser http://localhost:5173.

5. Use the application

There are two ways to interact with Dr. Claw: the frontend UI workflow or the terminal-only. The UI provides richer visualization but may encounter occasional bugs; the terminal approach is more stable and lightweight.

Option A: Frontend UI

Option B: Terminal Only

Option C: OpenRouter Terminal Chat

Option D: Desktop App

If agent web search does not work later, see Troubleshooting Web Search below.

OpenClaw Integration

1. Start the server

npm install && npm run dev       # or: drclaw server on
drclaw --json auth status        # verify reachability

drclaw server status only reports the daemon from drclaw server on. If you started Dr. Claw with npm run dev, it may show STOPPED even though http://localhost:3001 is working — use auth status as the real check.

2. Install the CLI

pip install -e ./agent-harness
drclaw --help

If drclaw is not on your PATH:

PYTHONPATH=agent-harness python3 -m cli_anything.drclaw.drclaw_cli --help

3. Authenticate

drclaw auth login --username  --password 
drclaw --json projects list      # should return your projects

4. Link OpenClaw

drclaw install --server-url http://localhost:3001
# with push channel:
drclaw install --server-url http://localhost:3001 --push-channel feishu:

This copies the Dr. Claw skill, installs wrapper scripts, and saves the server URL and CLI path.

5. Verify the core loop

Run these four commands from OpenClaw — if they all return valid JSON, the integration is live:

drclaw --json projects list                            # resolve projects
drclaw --json chat waiting                             # find sessions needing input
drclaw --json digest portfolio                         # cross-project summary
drclaw --json workflow status --project       # single-project status

6. Reply into a session

drclaw --json chat waiting                             # pick a session
drclaw --json chat reply --project  --session  -m “Continue with option B.”
drclaw --json chat waiting --project             # confirm it cleared

For multi-turn discussion within the same project:

drclaw --json chat project --project  --session  -m “Summarize blockers.”

---

Structured Schema

Machine-facing commands return a versioned openclaw field. Current families:

Client rendering tips:

Always prefer the openclaw payload over raw reply text when both are present.

Full contract: agent-harness/cli_anything/drclaw/SCHEMA.md

---

Proactive Watcher

The watcher is event-driven — it subscribes to Dr. Claw WebSocket events and only notifies on attention-worthy changes.

# Configure push channel
drclaw openclaw configure --push-channel feishu:

# Manage the watcher
drclaw --json openclaw-watch on --to feishu:
drclaw --json openclaw-watch status
drclaw --json openclaw-watch off

How it works:

WebSocket event → project resolution → snapshot diff → signal derivation
                                                          ↓
                         dedup (6h TTL) ← stable signature + signal kinds
                                                          ↓
                         openclaw agent --deliver → Feishu / Lark summary
                                (fallback: plain bridge push)

Derived signals:

State and logs:

• ~/.drclaw/openclaw-watcher-state.json
• ~/.drclaw/logs/openclaw-watcher.log

---

Serialized Local Turns

When OpenClaw calls openclaw agent --local repeatedly, use the wrapper script to avoid session-lock collisions:

agent-harness/skills/dr-claw/scripts/openclaw_drclaw_turn.sh \
  --json -m “Use your exec tool to run \`drclaw --json digest portfolio\`. Return only raw stdout.”

Rule of thumb: stable serial turns are always better than risky parallel turns.

---

Integration Checklist

Your OpenClaw integration is complete when all of these work:

• [ ] OpenClaw can list Dr. Claw projects
• [ ] OpenClaw can identify waiting sessions
• [ ] OpenClaw can reply into a chosen session
• [ ] OpenClaw can produce a digest portfolio summary
• [ ] OpenClaw receives at least one watcher-driven push in Feishu / Lark

At that point, OpenClaw becomes Dr. Claw’s mobile secretary. Users can speak naturally:

”Which projects are waiting for my reply?” ”Summarize this project’s progress and blockers.” ”Reply to that session: go with option B and report back.” ”Give me a cross-project summary and what to focus on today.” ”I have a new idea — create a project, discuss it with me, and start planning.”

Configuration

Dr. Claw reads local settings from .env. For most users, the only required step is copying .env.example to .env, but these are the settings you are most likely to adjust early:

• PORT: backend server port
• VITE_PORT: frontend dev server port
• HOST: bind address for the frontend and backend
• JWT_SECRET: required before exposing Dr. Claw beyond localhost
• WORKSPACES_ROOT: default root for new project workspaces

For the full environment reference and deployment notes, see docs/configuration.md.

Auto Research email notifications are configured inside the app at Settings → Email. The v1 flow supports Claude Code, Codex, Gemini, and OpenRouter engines for unattended task execution, and interrupted runs are automatically reconciled so they do not remain stuck in running.

Research Lab — Quick Example

The core feature of Dr. Claw is the Research Lab.

The typical flow is:

1. Configure one supported agent in Settings.
2. Configure notification settings in Settings → Email if you want completion email notifications.
3. Describe your research idea in Chat.
4. Let the agent generate .pipeline/docs/research_brief.json and .pipeline/tasks/tasks.json.
5. Review the pipeline in Research Lab and either send tasks back to Chat manually or click Auto Research on the Project Dashboard to run them sequentially.

For full step-by-step operations, see Usage Guide below.

Usage Guide

After starting Dr. Claw, open your browser and follow the steps below.

Describe your research idea — even a rough one is fine. The agent uses the inno-pipeline-planner skill to ask clarifying questions and then generates:

• .pipeline/docs/research_brief.json (your structured research brief)
• .pipeline/tasks/tasks.json (the task pipeline)

1. Choose a CLI backend from the CLI selector (Claude Code, Gemini CLI, or Codex).
2. In Research Lab, click Go to Chat or Use in Chat on a pending task.
3. The agent executes the task and writes results back to the project.

Claude Code Plugin

If you use Claude Code as your primary coding agent and want Dr. Claw’s research pipeline directly in your terminal — without running the full web UI — check out the standalone Claude Code plugin:

OpenLAIR/dr-claw-plugin-cc

The plugin provides 4 slash commands (/drclaw:setup, /drclaw:status, /drclaw:run, /drclaw:reset) that let you initialize research projects, track progress across all 5 pipeline stages, and execute tasks — all from within a Claude Code session.

Install

Inside any Claude Code session, run:

/plugin marketplace add OpenLAIR/dr-claw-plugin-cc
/plugin install dr-claw@dr-claw
/reload-plugins

The plugin is installed and will be available in future sessions. Run /drclaw:setup to initialize a new research project.

Scope options: By default the plugin is installed to your user scope (available in all projects). Add --scope project to install it for a specific project only, or --scope local for a machine-local install.

What’s Included

• 60+ bundled skills — a curated subset of Dr. Claw’s skill library covering literature survey, idea generation, experiment development, paper writing, and more
• 3 project templates — Method/Model, Dataset/Benchmark, and Position Paper, each with a pre-configured task pipeline
• Auto-detection — the plugin detects existing pipeline projects on session start and shows your current progress
• Same data format — projects created with the plugin use the same research_brief.json and tasks.json schemas as the full Dr. Claw workspace, so you can switch between them

Note: The plugin bundles a snapshot of skills from this repository. Skills are synchronized manually — see the plugin repo’s README for details.

Additional Details

Contributing

For setup help and troubleshooting, see FAQ.

Legacy Compatibility & Deprecation

Dr. Claw was previously known as VibeLab. For users migrating from VibeLab, we provide a compatibility layer during the transition phase:

• CLI Alias: The vibelab command is still supported as an alias for drclaw but will issue a deprecation warning.
• Python Package: The VibeLab class in the agent-harness is deprecated; please use the DrClaw class instead.
• Session Files: The CLI now defaults to ~/.drclaw_session.json but will automatically check for and migrate ~/.vibelab_session.json if found.
• Environment Variables: DRCLAW_URL and DRCLAW_TOKEN are preferred, but VIBELAB_URL and VIBELAB_TOKEN are still supported as fallbacks.

Timeline: We plan to remove legacy vibelab support in Version 2.0 (estimated Q3 2026). Please update your scripts and integrations as soon as possible.

License

This repository contains a combined work.

Upstream portions derived from Claude Code UI remain under GNU General Public License v3.0 (GPL-3.0), while original modifications and additions by Dr. Claw Contributors are licensed under GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE and NOTICE for the full license texts and scope details.

Citation

If you find Dr. Claw useful in your research, please cite:

@misc{song2026drclaw,
  author       = {Dingjie Song and Hanrong Zhang and Dawei Liu and Yixin Liu and Zongxia Li and Zhengqing Yuan and Siqi Zhang and Lichao Sun},
  title        = {Dr. Claw: An AI Research Workspace from Idea to Paper},
  year         = {2026},
  organization = {GitHub},
  url          = {https://github.com/OpenLAIR/dr-claw},
  homepage     = {https://openlair.github.io/dr-claw},
}

Acknowledgments

Built With

• Claude Code - Anthropic’s official CLI
• Gemini CLI - Google’s Gemini command-line agent
• Codex - OpenAI Codex
• React - User interface library
• Vite - Fast build tool and dev server
• Tailwind CSS - Utility-first CSS framework
• CodeMirror - Advanced code editor

Also Thanks To

• Claude Code UI — Dr. Claw is based on it. See NOTICE for details.
• AI Researcher (HKUDS) — Inspiration for research workflow and agentic research.
• Vibe-Scholar — Inspiration for the AI-native research workspace direction.
• autoresearch — Inspiration for autonomous research orchestration and end-to-end execution.
• Autoresearch (uditgoenka) — Autonomous goal-directed iteration engine, integrated as a tool pack in Auto Research Hub.
• ARIS — End-to-end autonomous research pipeline with cross-model adversarial review, integrated as a tool pack in Auto Research Hub.
• DeepScientist — 13-stage autonomous research OS from ICLR 2026, integrated as a tool pack in Auto Research Hub.

Support & Community

Stay Updated

• Star this repository to show support
• Watch for updates and new releases
• Follow the project for announcements

---