# nanoagentteam/research-claw architecture

> Architecture diagram of the GitHub repository nanoagentteam/research-claw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nanoagentteam/research-claw
- Repository: https://github.com/nanoagentteam/research-claw

## Overview

Research Claw is a self-hosted AI research assistant. Users interact through the CLI or messaging channels; the documented assistant workflow handles research and paper work, while project/session state supports continuing work. Major feature branches include literature search, LaTeX and Overleaf/Git workflows, multi-agent tasks, research automation, and memory. The map combines README-described capabilities with sampled imports and calls; some feature implementations were not sampled, so their internal links are omitted.

Main entry points: [`cli/main.py`](https://github.com/nanoagentteam/research-claw/blob/main/cli/main.py) (CLI), [`agent/loop.py`](https://github.com/nanoagentteam/research-claw/blob/main/agent/loop.py) (Agent loop), [`core/llm/engine.py`](https://github.com/nanoagentteam/research-claw/blob/main/core/llm/engine.py) (LLM engine), [`channels/feishu.py`](https://github.com/nanoagentteam/research-claw/blob/main/channels/feishu.py) (Chat channels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User access"]
  node_cli["CLI<br/>[main.py]"]
  node_gateway["Gateway<br/>[gateway_server.py]"]
  node_channels["Chat channels<br/>[feishu.py]"]
  node_queue["Message queue<br/>[queue.py]"]
  node_events["Message events<br/>[events.py]"]
end

subgraph group_agent["Assistant runtime"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_context["Prompt context<br/>[context.py]"]
  node_engine["LLM engine<br/>[engine.py]"]
  node_tool_loader["Tool loader<br/>[loader.py]"]
  node_tool_base["Tool interface<br/>[base.py]"]
  node_provider["LLM providers<br/>[openai_provider.py]"]
  node_config["Configuration<br/>[loader.py]"]
end

subgraph group_research["Research tools"]
  node_literature["Literature search<br/>[arxiv_search.py]"]
  node_pdf["PDF reading<br/>[web_reader.py]"]
end

subgraph group_work["Project work"]
  node_latex["LaTeX workflow<br/>[latex_tool.py]"]
  node_overleaf["Overleaf sync<br/>[olsync.py]"]
  node_git["Git history<br/>[git_agent.py]"]
  node_project["Projects<br/>[project.py]"]
  node_session["Sessions<br/>[session.py]"]
  node_task["Task agents<br/>[task_agent.py]"]
end

subgraph group_continuity["Memory and automation"]
  node_memory[("Memory store<br/>[store.py]")]
  node_history["History logging<br/>[logger.py]"]
  node_scheduler["Scheduled tasks<br/>[engine.py]"]
  node_radar["Research radar<br/>[autoplan.py]"]
  node_automation["Automation runtime<br/>[runtime.py]"]
end

node_user(("Researcher"))

node_user -->|"uses"| node_cli
node_user -->|"messages"| node_channels
node_cli -->|"creates"| node_loop
node_cli -->|"starts"| node_gateway
node_channels -->|"exchanges messages"| node_queue
node_queue -->|"carries"| node_events
node_loop -.->|"assembles context"| node_context
node_loop -.->|"runs reasoning"| node_engine
node_engine -->|"executes tools"| node_tool_base
node_engine -->|"requests completions"| node_provider
node_loop -.->|"loads tools"| node_tool_loader
node_user -->|"searches papers"| node_literature
node_user -->|"reads papers"| node_pdf
node_user -->|"writes papers"| node_latex
node_user -->|"syncs projects"| node_overleaf
node_user -->|"reviews changes"| node_git
node_user -->|"delegates work"| node_task
node_user -->|"sets tracking"| node_scheduler
node_scheduler -.->|"tracks research"| node_radar
node_user -->|"continues work"| node_memory
node_project -->|"creates sessions"| node_session
node_session -->|"records history"| node_history
node_context -->|"assembles memory"| node_memory
node_user -->|"automates research"| node_automation
node_cli -->|"loads settings"| node_config

click node_cli "https://github.com/nanoagentteam/research-claw/blob/main/cli/main.py"
click node_gateway "https://github.com/nanoagentteam/research-claw/blob/main/agent/services/gateway_server.py"
click node_channels "https://github.com/nanoagentteam/research-claw/blob/main/channels/feishu.py"
click node_queue "https://github.com/nanoagentteam/research-claw/blob/main/bus/queue.py"
click node_events "https://github.com/nanoagentteam/research-claw/blob/main/bus/events.py"
click node_loop "https://github.com/nanoagentteam/research-claw/blob/main/agent/loop.py"
click node_context "https://github.com/nanoagentteam/research-claw/blob/main/agent/context.py"
click node_engine "https://github.com/nanoagentteam/research-claw/blob/main/core/llm/engine.py"
click node_tool_loader "https://github.com/nanoagentteam/research-claw/blob/main/agent/tools/loader.py"
click node_tool_base "https://github.com/nanoagentteam/research-claw/blob/main/core/tools/base.py"
click node_provider "https://github.com/nanoagentteam/research-claw/blob/main/providers/openai_provider.py"
click node_literature "https://github.com/nanoagentteam/research-claw/blob/main/agent/tools/arxiv_search.py"
click node_pdf "https://github.com/nanoagentteam/research-claw/blob/main/core/tools/web_reader.py"
click node_latex "https://github.com/nanoagentteam/research-claw/blob/main/agent/tools/academic/latex_tool.py"
click node_overleaf "https://github.com/nanoagentteam/research-claw/blob/main/core/olsync_cstcloud/olsync.py"
click node_git "https://github.com/nanoagentteam/research-claw/blob/main/agent/git_agent.py"
click node_project "https://github.com/nanoagentteam/research-claw/blob/main/core/project.py"
click node_session "https://github.com/nanoagentteam/research-claw/blob/main/core/session.py"
click node_task "https://github.com/nanoagentteam/research-claw/blob/main/agent/task_agent.py"
click node_memory "https://github.com/nanoagentteam/research-claw/blob/main/core/memory/store.py"
click node_history "https://github.com/nanoagentteam/research-claw/blob/main/agent/memory/logger.py"
click node_scheduler "https://github.com/nanoagentteam/research-claw/blob/main/agent/scheduler/engine.py"
click node_radar "https://github.com/nanoagentteam/research-claw/blob/main/agent/radar_autopilot/autoplan.py"
click node_automation "https://github.com/nanoagentteam/research-claw/blob/main/core/automation/runtime.py"
click node_config "https://github.com/nanoagentteam/research-claw/blob/main/config/loader.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_gateway,node_channels,node_queue,node_events toneBlue
class node_loop,node_context,node_engine,node_tool_loader,node_tool_base,node_provider,node_config toneAmber
class node_literature,node_pdf toneMint
class node_latex,node_overleaf,node_git,node_project,node_session,node_task toneRose
class node_memory,node_history,node_scheduler,node_radar,node_automation,node_user toneIndigo
```

## Components

### User access

- [CLI](https://github.com/nanoagentteam/research-claw/blob/main/cli/main.py): `cli/main.py`
- [Gateway](https://github.com/nanoagentteam/research-claw/blob/main/agent/services/gateway_server.py): `agent/services/gateway_server.py`
- [Chat channels](https://github.com/nanoagentteam/research-claw/blob/main/channels/feishu.py): `channels/feishu.py`
- [Message queue](https://github.com/nanoagentteam/research-claw/blob/main/bus/queue.py): `bus/queue.py`
- [Message events](https://github.com/nanoagentteam/research-claw/blob/main/bus/events.py): `bus/events.py`

### Assistant runtime

- [Agent loop](https://github.com/nanoagentteam/research-claw/blob/main/agent/loop.py): `agent/loop.py`
- [Prompt context](https://github.com/nanoagentteam/research-claw/blob/main/agent/context.py): `agent/context.py`
- [LLM engine](https://github.com/nanoagentteam/research-claw/blob/main/core/llm/engine.py): `core/llm/engine.py`
- [Tool loader](https://github.com/nanoagentteam/research-claw/blob/main/agent/tools/loader.py): `agent/tools/loader.py`
- [Tool interface](https://github.com/nanoagentteam/research-claw/blob/main/core/tools/base.py): `core/tools/base.py`
- [LLM providers](https://github.com/nanoagentteam/research-claw/blob/main/providers/openai_provider.py): `providers/openai_provider.py`
- [Configuration](https://github.com/nanoagentteam/research-claw/blob/main/config/loader.py): `config/loader.py`

### Research tools

- [Literature search](https://github.com/nanoagentteam/research-claw/blob/main/agent/tools/arxiv_search.py): `agent/tools/arxiv_search.py`
- [PDF reading](https://github.com/nanoagentteam/research-claw/blob/main/core/tools/web_reader.py): `core/tools/web_reader.py`

### Project work

- [LaTeX workflow](https://github.com/nanoagentteam/research-claw/blob/main/agent/tools/academic/latex_tool.py): `agent/tools/academic/latex_tool.py`
- [Overleaf sync](https://github.com/nanoagentteam/research-claw/blob/main/core/olsync_cstcloud/olsync.py): `core/olsync_cstcloud/olsync.py`
- [Git history](https://github.com/nanoagentteam/research-claw/blob/main/agent/git_agent.py): `agent/git_agent.py`
- [Projects](https://github.com/nanoagentteam/research-claw/blob/main/core/project.py): `core/project.py`
- [Sessions](https://github.com/nanoagentteam/research-claw/blob/main/core/session.py): `core/session.py`
- [Task agents](https://github.com/nanoagentteam/research-claw/blob/main/agent/task_agent.py): `agent/task_agent.py`

### Memory and automation

- [Memory store](https://github.com/nanoagentteam/research-claw/blob/main/core/memory/store.py): `core/memory/store.py`
- [History logging](https://github.com/nanoagentteam/research-claw/blob/main/agent/memory/logger.py): `agent/memory/logger.py`
- [Scheduled tasks](https://github.com/nanoagentteam/research-claw/blob/main/agent/scheduler/engine.py): `agent/scheduler/engine.py`
- [Research radar](https://github.com/nanoagentteam/research-claw/blob/main/agent/radar_autopilot/autoplan.py): `agent/radar_autopilot/autoplan.py`
- [Automation runtime](https://github.com/nanoagentteam/research-claw/blob/main/core/automation/runtime.py): `core/automation/runtime.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: uses (evidence: `README`)
- Researcher → Chat channels: messages (evidence: `README`)
- CLI → Agent loop: creates (evidence: `cli/main.py`)
- CLI → Gateway: starts (evidence: `cli/main.py`)
- Chat channels → Message queue: exchanges messages (evidence: `channels/feishu.py`)
- Message queue → Message events: carries (evidence: `bus/queue.py`)
- Agent loop → Prompt context: assembles context
- Agent loop → LLM engine: runs reasoning
- LLM engine → Tool interface: executes tools (evidence: `core/llm/engine.py`)
- LLM engine → LLM providers: requests completions (evidence: `core/llm/engine.py`)
- Agent loop → Tool loader: loads tools
- Researcher → Literature search: searches papers (evidence: `README`)
- Researcher → PDF reading: reads papers (evidence: `README`)
- Researcher → LaTeX workflow: writes papers (evidence: `README`)
- Researcher → Overleaf sync: syncs projects (evidence: `README`)
- Researcher → Git history: reviews changes (evidence: `README`)
- Researcher → Task agents: delegates work (evidence: `README`)
- Researcher → Scheduled tasks: sets tracking (evidence: `README`)
- Scheduled tasks → Research radar: tracks research
- Researcher → Memory store: continues work (evidence: `README`)
- Projects → Sessions: creates sessions (evidence: `core/session.py`)
- Sessions → History logging: records history (evidence: `core/session.py`)
- Prompt context → Memory store: assembles memory (evidence: `agent/context.py`)
- Researcher → Automation runtime: automates research (evidence: `README`)
- CLI → Configuration: loads settings (evidence: `cli/main.py`)
