research-claw

Your self-hosted AI research assistant

Manage papers · search literature · track deadlines · collaborate across channels

Quick Start  ·  Features  ·  How It Works  ·  Docs

English  |  中文

Table of Contents

• What is Research Claw?
• Key Features
• Getting Started
• How It Works
• Configuration Reference
• Documentation
• Contributing
• License

What is Research Claw?

Research Claw is a personal AI research assistant you run on your own machine. It manages your LaTeX projects, syncs with Overleaf, searches literature, tracks deadlines — and answers you on the channels you already use (CLI, Web UI, Telegram, Feishu, QQ, DingTalk).

Instead of switching between your editor, Overleaf, terminal, and search engine, you talk to one assistant that handles it all:

You: Create a paper project "MoE-Survey" and link it to Overleaf.
Bot: ✅ Project created. Overleaf linked. Switched to MoE-Survey.

You: Research the latest MoE papers and draft an introduction.
Bot: 🔎 Searching arXiv... 📝 Writing introduction... ✅ Compiled successfully.

You: /sync push
Bot: ✅ Pushed 3 files to Overleaf.

Interactive CLI session

Key Features

Getting Started

1. Install

Linux / macOS:

git clone https://github.com/nanoAgentTeam/research-claw.git
cd research-claw

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

NAME            FRIENDLY NAME
Ubuntu          Ubuntu
Ubuntu-18.04    Ubuntu 18.04 LTS
Ubuntu-20.04    Ubuntu 20.04 LTS

wsl --install -d Ubuntu-20.04

sudo apt update && sudo apt install -y python3.11 python3.11-venv python3-pip git

# Recommended: keep code on the Linux filesystem for better performance
git clone https://github.com/nanoAgentTeam/research-claw.git ~/research-claw
cd ~/research-claw

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Option A: install directly
sudo apt install -y chromium-browser

# Option B: via playwright
pip install playwright && playwright install --with-deps chromium

2. Configure

# Start the gateway — this launches the Web UI
python cli/main.py gateway --port 18790

Open http://localhost:18790/ui in your browser:

1. Provider Management — Add your LLM provider (API Key, model name, base URL). Any OpenAI-compatible API works (GPT, DeepSeek, Qwen, Claude, etc.)
2. Channel Accounts — (optional) Add IM bot credentials (Feishu / Telegram / QQ / DingTalk)
3. Push Subscriptions — (optional) Configure where automation results get delivered

All settings are stored in settings.json. Advanced users can edit this file directly — see Configuration Reference.

Web UI — Provider & Channel configuration

3. Overleaf Authorization (optional)

Overleaf sync enables bidirectional sync between your local LaTeX project and Overleaf — every AI edit can be pushed, and every collaborator's edit can be pulled.

python cli/main.py login

This will prompt you to choose an Overleaf instance:

The login command will call the corresponding login tool, generate .olauth, and save the instance config to settings.json.

Once .olauth is created, the system auto-detects it. Use /sync pull and /sync push inside any project.

4. Run

Option A — CLI — interact directly in your terminal:

python cli/main.py agent

Option B — Gateway — Web UI + IM channels, chat from anywhere:

python cli/main.py gateway --port 18790

How It Works

Architecture

graph TB
    subgraph Channels["Access Channels"]
        direction LR
        CLI["CLI"]
        WebUI["Web UI"]
        Feishu["Feishu"]
        TG["Telegram"]
        QQ["QQ"]
        DT["DingTalk"]
    end

    Channels --> MB["MessageBus"]
    MB --> AL["AgentLoop — Main Agent"]
    AL --> CR["CommandRouter"]
    AL --> CM["ContextManager"]
    AL --> TR["ToolRegistry (40+ tools)"]
    AL --> SA["Sub-Agents (Workers)"]

    TR --> Proj["Project\nGit · LaTeX · Overleaf"]
    TR --> LLM["LLM Provider\nOpenAI-compatible · Hot-swap"]
    TR --> Auto["Automation\nScheduled cron jobs"]

Workspaces

The system has two spaces:

workspace/
├── Default/                    # Lobby — project management & chat
└── MyPaper/
    ├── project.yaml            # Project config
    ├── MyPaper/                # Core directory (LaTeX files + Git repo)
    │   ├── main.tex
    │   └── references.bib
    └── 0314_01/                # Session (conversation history, sub-agent workspace)

Commands

Task Mode

For multi-step goals, /task decomposes work into a 5-phase multi-agent pipeline:

1. You type:  /task Write a survey on Mixture-of-Experts

2. [UNDERSTAND]  Bot reads your project files automatically.

3. [PROPOSE]     Bot shows you a proposal (scope, deliverables, approach).
   → Review it. Reply with feedback to revise, or say "ok" to proceed.

4. [PLAN]        Bot shows you a task DAG (sub-tasks, dependencies, assigned agents).
   → Review it. Reply with changes, or type /start to begin execution.

5. [EXECUTE]     Sub-agents run tasks in parallel batches. Real-time progress:
                 📦 Batch 1 | 2 tasks in parallel: [t1, t2]
                 ✅ Batch 1 complete (45s) — Progress: 2/8
                 ...

6. [FINALIZE]    Bot merges all worker outputs and commits.
   → Type /done to exit task mode.

Task mode — parallel sub-agent execution

Multi-Agent Collaboration

You: "Write a paper about MoE"

Main Agent:
  1. Creates "researcher" sub-agent → searches literature in sandbox
  2. Creates "writer" sub-agent → drafts sections in sandbox
  3. Reviews and merges outputs into project
  4. Compiles and syncs to Overleaf

Sub-agents work in isolated overlay directories. Their outputs go through a merge process before touching the project core — no accidental overwrites.

Automation & Research Radar

Each project can have scheduled tasks that run automatically via cron expressions. Configure them through the Web UI's Automation tab or via project.yaml.

How it works: Gateway starts APScheduler → each job fires at its cron schedule, spawns an agent session → agent reads project memory, runs searches, writes findings → results pushed to configured channels (Telegram, Feishu, Email, etc.).

Automation dashboard — radar jobs & push notifications

Configuration Reference

All runtime config lives in settings.json (managed via Web UI, or edit directly):

Skills

Skills are domain-specific SOPs the agent activates on demand. Add a custom skill by creating a folder under config/.skills/:

config/.skills/
└── my-skill/
    ├── SKILL.md          # Required — skill definition (YAML frontmatter)
    └── templates/        # Optional — resource files

The system auto-discovers all skill folders at startup — no registration needed.

Documentation

IM Setup: Feishu · Telegram · QQ · DingTalk

Push Subscriptions: Configuration Guide

Contributing

Contributions are welcome! Feel free to:

• Open an Issue for bugs or feature requests
• Submit a Pull Request with improvements
• Improve documentation or add new venue skill templates

License

MIT License — free for academic and commercial use.