Dr. Claw: Your AI Research Assistant

Full-stack research workspace.

English | 中文

• Overview
• Highlights
• Quick Start
• Configuration
• OpenClaw Integration
• Research Lab - Quick Example
• Usage Guide
• Additional Details
• Contributing
• FAQ
• License
• Citation
• Acknowledgments
• Support & Community

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.

• 🔬 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, and Codex as your execution engines

• 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.

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

5. Open your browser at http://localhost:5173 (or the port you configured in .env)

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

This section is written for new users integrating OpenClaw with Dr. Claw for the first time. The goal is not to expose every detail. The goal is to get a reliable first integration running quickly:

• OpenClaw can see which Dr. Claw projects exist
• OpenClaw can find sessions waiting for user input
• OpenClaw can reply into a chosen session so Dr. Claw keeps going
• OpenClaw can summarize project / portfolio progress and recommend what to focus on next

The clean mental model is:

• Dr. Claw: owns the real projects, sessions, pipelines, artifacts, and execution
• drclaw CLI: exposes that state through a stable local control surface exposed primarily as drclaw
• OpenClaw: acts as the user-facing secretary on mobile, chat, or voice

If you only want the shortest successful path, do these 5 things:

1. Start Dr. Claw
2. Install the drclaw CLI
3. Give OpenClaw local shell / exec access
4. Install the provided OpenClaw skill
5. Make chat waiting and digest portfolio work end-to-end

Once those two commands work, OpenClaw already behaves like a usable research secretary.

Before integrating, make sure:

• you can already run Dr. Claw locally
• you already have at least one project, or can create one under ~/vibelab/...
• you have configured at least one execution backend such as Claude Code, Gemini CLI, or Codex
• your OpenClaw instance is allowed to run local tools

If those are not true yet, get Dr. Claw itself working first.

From the repo root:

npm install
npm run dev

In another terminal:

drclaw --json auth status
drclaw server status

Use auth status as the primary reachability check. If it returns JSON, the server is reachable.

drclaw server status only reports the daemon launched by drclaw server on. If you started the app manually with npm run dev, it may still show STOPPED even though http://localhost:3001 is working.

If you want Dr. Claw to manage the background process for you:

drclaw server on

From the repo root:

pip install -e ./agent-harness

Then verify:

drclaw --help
drclaw --json auth status
drclaw --json projects list

A good sequence is:

• drclaw --json auth status should return JSON if the server is reachable
• drclaw --json projects list will work only after login or if you already have a saved token

If projects list returns Not logged in, authenticate first:

drclaw auth login --username <username> --password <password>

The key integration is not a deep API bridge. The key is that OpenClaw can directly execute drclaw ... locally.

At minimum, OpenClaw should be able to run commands such as:

drclaw --json chat waiting
drclaw --json digest portfolio
drclaw --json chat reply --project <project> --session <session-id> -m "<message>"
drclaw --json workflow continue --project <project> --session <session-id> -m "<instruction>"

Recommended approach:

• enable local exec / shell for OpenClaw
• prefer direct local CLI calls
• avoid building an extra proxy layer at the beginning

The thinner this layer is, the easier it is to debug and keep reliable.

Run:

drclaw install --server-url http://localhost:3001

This will automatically:

• copy the Dr. Claw skill into ~/.openclaw/workspace/skills/drclaw
• install the helper scripts OpenClaw uses for serialized local turns
• save the Dr. Claw server URL for future CLI / OpenClaw use
• remember the local drclaw executable path

If you also want to save the default push channel during setup:

drclaw install --server-url http://localhost:3001 --push-channel feishu:<chat_id>

The compatibility form is still available:

drclaw openclaw install --server-url http://localhost:3001

For a new user, do not start with everything. Start with these two:

1. Find which sessions are waiting for user input

drclaw --json chat waiting

2. Get portfolio-wide progress and recommendations

drclaw --json digest portfolio

If OpenClaw can call both commands and summarize the result back to the user, your minimum viable integration is already working.

The next common user action is: see a waiting session, then ask OpenClaw to answer it.

The fixed pattern is:

1. Find waiting sessions:

drclaw --json chat waiting

2. Let the user choose a project and session

3. Send the reply:

drclaw --json chat reply --project <project> --session <session-id> -m "<message>"

4. Immediately re-check whether it is still waiting:

drclaw --json chat waiting --project <project>

If the user wants to keep discussing the same project/session, switch to:

drclaw --json chat project --project <project> --session <session-id> -m "<instruction>"

That is the better pattern for multi-turn project-scoped discussion.

Recommended OpenClaw flows:

1. User asks: what needs my attention right now?

drclaw --json digest portfolio

2. User asks: which sessions are waiting for me?

drclaw --json chat waiting

3. User asks: what is the latest state of this project?

drclaw --json projects latest <project>
drclaw --json projects progress <project>

4. User says: reply to this session and keep it moving

drclaw --json chat reply --project <project> --session <session-id> -m "<message>"

5. User says: I just had a new idea, create a project and help me shape it

drclaw --json projects idea /absolute/path/to/project --name "<display-name>" --idea "<idea text>"

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

agent-harness/skills/dr-claw/scripts/openclaw_drclaw_turn.sh

Example:

openclaw_drclaw_turn.sh --json -m "Use your exec tool to run `drclaw --json digest portfolio`. Return only raw stdout."

In practice: when OpenClaw calls Dr. Claw locally, stable serial turns are better than risky parallel turns.

A new user can consider the integration complete once all 4 are true:

• OpenClaw can list Dr. Claw projects
• OpenClaw can identify waiting sessions
• OpenClaw can successfully send one reply into a chosen session
• OpenClaw can produce one digest portfolio style summary with recommendations

At that point, OpenClaw is no longer just a chat surface. It becomes Dr. Claw's mobile secretary.

After setup, users should be able to talk to OpenClaw naturally:

• “Check which Dr. Claw projects are waiting for my reply.”
• “Summarize the last message and current progress of this project.”
• “Reply to this session: continue with option B and report back when finished.”
• “Summarize recent experiment progress across projects and recommend what I should focus on today.”
• “I just had a new idea. Create a Dr. Claw project, discuss it with me, refine it, and start execution planning.”

The goal is not to replace Dr. Claw. The goal is to make Dr. Claw callable, reportable, steerable, and remotely manageable through OpenClaw.

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, and Gemini engines for unattended task execution, and interrupted runs are automatically reconciled so they do not remain stuck in running.

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.

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

echo "${CODEX_SANDBOX_NETWORK_DISABLED:-0}"

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │  Agent          │
│   (React/Vite)  │◄──►│ (Express/WS)    │◄──►│  Integration    │
│                 │    │                 │    │                │
└─────────────────┘    └─────────────────┘    └─────────────────┘

For setup help and troubleshooting, see FAQ.

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.

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.

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 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},
}

• 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

• 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.

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