DeepScientist: Instructions file for Codex

DeepScientist Repository Guide

This AGENTS.md applies to the entire repository.

It is the repository-level guide for coding agents and maintainers working in this checkout. It should describe the code and docs that actually exist here today.

When code and docs diverge, prefer the current runtime behavior and tests, then update the docs in the same change.

Mission

Build DeepScientist as a small, local-first research operating system that:

• runs on the user's machine by default
• installs cleanly through npm
• keeps the authoritative runtime in Python
• uses prompt-led and skill-led workflow control
• stores durable state in files plus Git
• keeps one quest as one Git repository
• supports the full research loop inside one quest workspace

The target is a focused core runtime, not a large platform.

Read First

Do not start from memory. Start from the files that actually exist.

Recommended reading order for coding agents:

1. README.md
2. docs/en/README.md
3. docs/en/90_ARCHITECTURE.md
4. docs/en/91_DEVELOPMENT.md
5. the smallest subsystem-specific doc set that matches the task
6. the actual implementation under src/
7. the relevant tests under tests/

Important current docs by topic:

• product and docs index:
  • README.md
  • docs/en/README.md
  • docs/zh/README.md
• maintainer architecture and workflow:
  • docs/en/90_ARCHITECTURE.md
  • docs/en/91_DEVELOPMENT.md
• user-facing architecture and workflow:
  • docs/en/13_CORE_ARCHITECTURE_GUIDE.md
  • docs/en/14_PROMPT_SKILLS_AND_MCP_GUIDE.md
  • docs/en/06_RUNTIME_AND_CANVAS.md
  • docs/en/07_MEMORY_AND_MCP.md
• runtime and settings:
  • docs/en/00_QUICK_START.md
  • docs/en/01_SETTINGS_REFERENCE.md
  • docs/en/05_TUI_GUIDE.md
  • docs/en/09_DOCTOR.md
  • docs/en/31_LOCAL_BROWSER_AUTH.md
  • docs/en/20_WORKSPACE_MODES_GUIDE.md
• runner/provider setup:
  • docs/en/15_CODEX_PROVIDER_SETUP.md
  • docs/en/24_CLAUDE_CODE_PROVIDER_SETUP.md
  • docs/en/25_OPENCODE_PROVIDER_SETUP.md
  • docs/en/27_KIMI_CODE_PROVIDER_SETUP.md
  • docs/en/21_LOCAL_MODEL_BACKENDS_GUIDE.md
• connectors:
  • docs/en/03_QQ_CONNECTOR_GUIDE.md
  • docs/en/04_LINGZHU_CONNECTOR_GUIDE.md
  • docs/en/10_WEIXIN_CONNECTOR_GUIDE.md
  • docs/en/16_TELEGRAM_CONNECTOR_GUIDE.md
  • docs/en/17_WHATSAPP_CONNECTOR_GUIDE.md
  • docs/en/18_FEISHU_CONNECTOR_GUIDE.md
  • docs/en/19_EXTERNAL_CONTROLLER_GUIDE.md
• BenchStore:
  • docs/en/22_BENCHSTORE_YAML_REFERENCE.md
  • docs/en/23_BENCHSTORE_GITHUB_RELEASES_SPEC.md