Home

Relevant source files

• .gitignore
• README.md
• README_ZH.md
• assets/home.png
• assets/start.png
• assets/wechat.png
• docs/en/19_EXTERNAL_CONTROLLER_GUIDE.md
• docs/en/README.md
• docs/zh/19_EXTERNAL_CONTROLLER_GUIDE.md
• docs/zh/README.md

DeepScientist is a local-first AI research operating system designed to transform fragmented, manual research tasks into a durable, executable, and cumulative AI workspace. Unlike "research chatbots" that lose context, DeepScientist manages the entire research lifecycle—from literature scouting and baseline reproduction to experiment execution and paper writing—within a structured, version-controlled environment.

Core Philosophy: One Quest = One Git Repo

The fundamental unit of work in DeepScientist is the Quest. Every research objective (e.g., "Reproduce Paper X" or "Optimize Algorithm Y") is initialized as a dedicated Git repository. This design choice ensures:

• Durable State: Every turn, file change, and experiment result is committed or tracked in durable files README.md139-142
• Research Lineage: Branches and worktrees naturally represent hypothesis branching, ablation studies, and paper drafts README.md139-142
• Human-in-the-loop: Researchers can pause the agent, edit code or plans directly in the repo, and resume the agent from the new state README.md149-152

Key Capabilities

DeepScientist provides an end-to-end autonomous research pipeline driven by Stage Skills rather than hard-coded logic docs/en/README.md70-71

Capability	Technical Implementation
Baseline Reproduction	Automated environment setup, dependency handling, and smoke testing README.md97-99
Experimentation	Managed hypothesis branching using Git worktrees and persistent bash_exec sessions docs/zh/README.md19-23
Scientific Writing	Integrated Tiptap/Novel editor with LaTeX support and automated figure generation README.md109-111
Cross-Surface Collaboration	Uniform API access via Web UI, TUI, and external Connectors (WeChat, Telegram, etc.) README.md113-118
Memory & Artifacts	RAG-based memory retrieval and a "Metric Contract" for tracking research progress docs/en/README.md74-75

Sources: README.md89-118 docs/en/README.md3-9 docs/zh/README.md19-24

---

System Architecture Overview

DeepScientist utilizes a hybrid architecture: a Node.js Launcher manages the lifecycle and UI, while a Python Daemon handles the research logic, turn execution, and tool orchestration.

From Natural Language to Code Entities

The following diagram bridges the gap between the user's research quest and the underlying system components.

Quest Execution and Data Flow

Sources: docs/en/README.md68-73 docs/zh/README.md114-119 docs/en/19_EXTERNAL_CONTROLLER_GUIDE.md31-40

---

Research Workflow and Skill Delegation

DeepScientist does not use a rigid state machine. Instead, the PromptBuilder assembles a context-rich prompt that allows the LLM to select and execute specific Skills based on the current research stage.

Skill and Tool Orchestration

Sources: docs/en/README.md70-71 docs/en/19_EXTERNAL_CONTROLLER_GUIDE.md46-58 docs/zh/README.md122-123

---

Wiki Organization

This wiki is organized to support both users and developers:

1. Home: Overview and core philosophy (Current Page).
2. Core Architecture: Deep dive into the hybrid runtime and daemon design.
   • Launch Chain: From npm install to the running daemon.
   • Quest Model: How Git repositories store research state.
   • Daemon API: Turn scheduling and the CodexRunner.
3. Prompt System and Skills: How the agent "thinks" and acts.
   • Prompt Assembly: The 17-layer context synthesis pipeline.
   • Stage Skills Reference: Detailed guide to research stages (Scout, Idea, etc.).
   • MCP Tools: bash_exec, artifact, and memory tool semantics.
4. Artifact and Memory Services: Managing research knowledge.
   • ArtifactService: Tracking experiments and the Evidence Ledger.
   • Memory Service: RAG, Arxiv integration, and cross-turn memory.
5. User Interfaces: Interacting with the system.
   • Web Workspace: Lab Canvas, scientific editor, and noVNC.
   • TUI: Terminal-based interaction for remote servers.
   • CLI & Config: Configuration YAMLs and ds command reference.
6. Connectors: Bridging to external platforms.
   • Platform Guides: WeChat, Telegram, Slack, etc.
   • External Controller: Building custom governance layers.
7. Development & Ops: Setup, testing, and contribution.

Sources: docs/en/README.md27-94 docs/zh/README.md73-140