deer flow

The Problem

Teams that need an autonomous “research‑to‑code” pipeline must stitch together LLM calls, file‑system sandboxes, long‑term memory, and external tools. Doing this manually leads to duplicated glue code, fragile error handling, and a high cognitive load for new contributors.

What This Does

deer‑flow is a self‑contained super‑agent harness that coordinates sub‑agents, memories, and sandboxed execution.

• The backend (backend/src/…) implements a FastAPI gateway, a configurable agent factory, and an async sandbox layer (backend/src/community/aio_sandbox).
• The frontend (frontend/src/…) supplies a React/Next UI that visualises threads, messages, and skill‑driven artefacts.
• Skills (skills/…) are reusable tool definitions (e.g., GitHub crawling, Claude code integration) that can be loaded at runtime.
• Docker support (docker/…) lets you spin up the whole stack with a single compose file.

How It Is Wired

1. Entry point – backend/src/gateway/app.py defines the FastAPI lifespan hook (line 32) that builds the application configuration via get_app_config (called 24 times across the repo).
2. get_app_config reads backend/src/config/app_config.py, which resolves environment variables, loads model/tool definitions, and returns a structured config used by every agent.
3. The gateway creates a sandbox provider (backend/src/community/aio_sandbox/aio_sandbox_provider.py). This module has the highest inbound degree (Ca 1, Ce 7, instability 0.88) and performs a cryptographic secret generation and an outbound HTTP call during backend startup.
4. Agent factories (backend/src/agents/lead_agent/agent.py, backend/src/agents/memory/updater.py) pull the config, instantiate LangChain chat models (create_chat_model – called 21 times), and wire middleware such as memory_middleware and title_middleware.
5. The message bus (MessageBus, publish_inbound, subscribe_outbound) is the busiest hub: go invokes it from 30 different callers, propagating inbound/outbound messages to sub‑agents.
6. External effects: - Network – start → _dispatch_loop → _handle_message → _fetch_gateway triggers an HTTP GET. - Filesystem – main → generate_html reads template files to render demo HTML. - Database – a handful of functions (4 total) perform reads/writes via SQLite helpers.

The internal call graph shows no circular dependencies and a single‑direction flow from configuration → sandbox → agents → message bus → UI. The most “blast‑radius” functions (_make_paths, get_paths, create_chat_model) are referenced by > 20 callers each, so changes there ripple widely.

How To Use It

# 1. Clone the repository
git clone https://github.com/moses-y/deer-flow.git
cd deer-flow

# 2. Generate local config files (README‑provided)
make config

# 3. Run the stack locally (Docker recommended)
docker compose -f docker/docker-compose-dev.yaml up --build

# 4. Or develop front‑end only
pnpm install        # pnpm is the declared package manager
pnpm dev            # starts Next.js dev server

The backend can also be launched directly (see backend/Makefile for a run target) which executes backend/src/gateway/app.py via uvicorn. Environment variables such as OPENAI_API_KEY are read by backend/src/config/app_config.py and must be present in a .env derived from .env.example.

Real‑World Use

A product team can embed deer‑flow as a “research assistant” micro‑service. An incoming request hits the FastAPI gateway, which spawns a sub‑agent that uses the InfoQuest skill to crawl the web, stores snippets in the long‑term memory module, and finally returns a generated code snippet to the UI. The whole flow requires only the config YAML to point at the desired LLM and API keys.

Code Health & Issues

Audit findings (static‑analysis confirmed):

Measured code‑quality findings:

• High cognitive load – deep nesting (max depth 14) in backend/src/community/aio_sandbox/remote_backend.py, backend/src/subagents/executor.py, and frontend/src/components/landing/progressive-skills-animation.tsx.
• Duplicated code – identical 6‑line blocks appear in 48 files (e.g., channel adapters).
• Oversized files – backend/tests/test_client.py exceeds 1,200 lines, making localized changes risky.
• Broad exception handling – 18 places swallow generic Exception, reducing observability.
• Resource safety – three open(...) calls lack context managers.

No critical issues were detected, and the repository includes tests, CI, a licence, and lockfiles.

The Bottom Line

deer‑flow delivers a modular super‑agent platform with clear separation between UI, backend, and skill libraries, making it suitable for teams that need a configurable LLM orchestration layer. However, the codebase suffers from deep nesting, duplicated snippets, and lax security hygiene; addressing these will lower maintenance cost and improve production safety.