deer-flow/AGENTS.md

DeerFlow

DeerFlow is an agent harness: a LangGraph-based backend with thread-isolated sandboxes, memory, subagents, skills and MCP tools, and a Next.js frontend. IM channels connect through the Gateway. CLAUDE.md imports this file; edit guidance here, not in the shim.

How guidance is organized

Rules live in the AGENTS.md nearest to the code. Before you edit a directory, read every AGENTS.md from that directory up to this file. Some coding agents do not load the nested files on their own.

Area	Guide
Backend: harness, Gateway, channels, tests	backend/AGENTS.md
Frontend	frontend/AGENTS.md
nginx, Compose, provisioner	docker/AGENTS.md
Orchestration scripts, scripts/pnpm.py	scripts/AGENTS.md
Skill review, skill tests	skills/AGENTS.md
Extension examples	examples/*/AGENTS.md

Humans start at README.md, CONTRIBUTING.md and docs/guide/.

Service topology

Service	Port	Role
Nginx	2026	The single entry point; open this in the browser
Gateway	8001	FastAPI REST API and the embedded agent runtime
Frontend	3000	Next.js web interface
Provisioner	8002	Optional; only for provisioner or Kubernetes sandboxes

Nginx serves the frontend, proxies /api/* to the Gateway and rewrites /api/langgraph/* to the Gateway's native routes.

Before changing ingress, port bindings or provisioner mounts, read service topology details.

Repository map

Path	Content
backend/packages/harness/	deerflow-harness, import deerflow.*: the agent framework
backend/packages/extension-api/	deerflow-extension-api: the public extension contract
backend/app/	The Gateway and the IM channels, import app.*
frontend/	The Next.js app (pnpm)
docker/, deploy/helm/	Compose files, nginx config, provisioner, Helm chart
skills/public/, skills/custom/	Committed skills and local, gitignored skills
contracts/	JSON contracts shared across components
examples/	Installable extension examples
scripts/, tests/	Root orchestration scripts, and tests for public skills

config.yaml and extensions_config.json are copied from the example files at the repository root. Both are gitignored and the Gateway can write them. Do not commit them.

Commands

make help lists the root targets. First setup is make config, then make install, then make dev, which serves the stack on localhost:2026 and writes logs/gateway.log and logs/frontend.log.

cd backend && make test && make test-blocking-io   # offline suites
cd backend && make format                          # CI runs ruff format --check
cd backend && python -m pytest tests/path/test_x.py::test_name -q
cd frontend && pnpm check && pnpm test
cd frontend && pnpm rstest run <pattern>
make check-agent-guidance                          # size budget of these guides

Rules for every change

• Evaluate an extension first. Before you add a feature to core code, check whether it can ship as a packaged extension. Core is the place for bug fixes and for changes to the agent loop, memory, context compaction and authentication. When the existing hooks cannot express a feature, add a generic hook to the extension contract and an extension that uses it; business logic is not hard-coded into core. Contract and examples: extensions guide, examples/.
• Extensions are operator-controlled code. They load from plugins: in config.yaml. The list stays out of the API-writable extensions_config.json, because loading an extension imports code with Gateway privileges. Install from trusted sources only, and restart the Gateway after every extension change.
• Ship tests with every feature and bug fix.
• Document behavior next to its topic, in the same change: user-facing behavior in docs/guide/ or backend/docs/. README.md is an index; change it only to add or re-point a link.
• Keep the version fields identical: backend/pyproject.toml, backend/packages/harness/pyproject.toml, frontend/package.json, and version and appVersion in deploy/helm/deer-flow/Chart.yaml. scripts/bump_version.sh <ver> updates them and backend/uv.lock, and scripts/verify_versions.sh <ver> checks the result. Tag CI blocks publishing on drift. See RELEASING.md.

What belongs in an AGENTS.md

An agent reads these files on every task, so each line costs attention. A guide holds four kinds of content:

1. Scope: what the directory owns, in one or two sentences.
2. Verification: the exact commands.
3. Traps: where the code misleads, or where a plausible change breaks something that a local test run does not show.
4. Decisions and their reasons that the code cannot state, and links to docs.

Values, defaults, field lists, function inventories, test names, issue numbers and history stay in the code, the tests and git. Write full sentences in the positive form and give the reason. make check-agent-guidance enforces the size budget.

Office preview example

examples/deerflow-extension-office-preview/ packages Office readers through the optional artifactPreviews browser contract. Keep parser dependencies and resources in the extension; rebuild its manifest and static module graph after UI changes. Test packaged assets with the Office E2E fixtures; rendering must preserve original downloads and state its search limits.