DeerFlow

What It Does

DeerFlow (Deep Exploration and Efficient Research Flow) is ByteDance's open-source super-agent harness, built on LangGraph and LangChain. Version 2.0 is a ground-up rewrite that shares no code with the original v1 Deep Research framework. It orchestrates sub-agents, persistent memory, sandboxed execution, and extensible skills to handle tasks that range from minutes to hours. The backend is a FastAPI Gateway with an embedded LangGraph runtime (219,815 lines of Python across 382 test files). The frontend is a Next.js chat UI. External IM platforms (Feishu, Slack, Telegram, Discord, DingTalk, WeCom) bridge into the same agent through a Gateway. The target users are developers and teams who want a self-hosted, full-stack agent platform with a first-class skills system rather than a hosted API or a single-purpose tool. At 76,583 stars and 10,398 forks, it is one of the most adopted open-source agent projects on GitHub, and it claimed the number one spot on GitHub Trending on February 28, 2026 following the 2.0 launch.

The Good

The skills system is more security-conscious than most standalone skill scanners, and the evidence is in the code. The SkillScan orchestrator (backend/packages/harness/deerflow/skills/skillscan/orchestrator.py) runs as a native deterministic scanner before any LLM-based review. It defines 18 rule specs across two phases: package-level checks (path traversal, absolute paths, symlinks, nested SKILL.md, oversized archives at 512MB total and 64MB per file, more than 4,096 members, executable binaries, nested archives, hidden sensitive files, .git directories) and content-level checks (private keys, cloud tokens, env assignments with non-placeholder values, prompt override phrases, sensitive capability declarations, sensitive path references, external endpoints). CRITICAL findings block installation. WARNING findings pass to the LLM scanner for contextual review. This is the same defense-in-depth pattern RAPTOR uses for its own supply chain, but here it is applied to every skill a user installs or creates through the skill_manage tool, not just the framework's own dependencies.

The test coverage for skills is real and verifiable, not a claim on a README. Running pytest tests/skills/ from the repo root executes 51 tests in 0.07 seconds, covering the music-generation skill (9 tests: lyrics payload handling, instrumental flag, lyrics-optimizer fallback, model override, base_resp error propagation, missing API key, missing audio data, empty prompt, empty lyrics fallback), the podcast-generation skill (14 tests: provider resolution for Volcengine and MiniMax, TTS hex decoding, voice mapping, end-to-end generation, retry on rate-limit HTTP 429, no-retry on auth errors, max-retry exhaustion, partial-failure propagation, worker count defaults), and the video-generation skill (12 tests: provider resolution for Gemini and MiniMax, full flow, reference first frame, task failure, poll timeout, task context retention, HTTP error handling, nested directory writes). Every test mocks the HTTP layer with a FakeResp class, so they run without API keys and assert on the actual request payloads, headers, and error paths. Running pytest tests/ -k "skill" in the backend exercises 670 more tests (skill parser, SkillScan rules, skill storage, slash activation, secret binding, deferred discovery) in 9.42 seconds with 2 skipped. The total collected test count is 6,776.

The skill format extends the standard SKILL.md spec with security primitives that other skill systems lack. The parser (backend/packages/harness/deerflow/skills/parser.py) accepts YAML frontmatter fields beyond name and description: allowed-tools (a whitelist tuple that restricts which tools a skill may invoke), required-secrets (a list of environment variable names the skill needs, each optionally marked optional), and secrets-autonomous (a boolean that controls whether declared secrets bind during autonomous in-context activation or only on explicit /slash activation). The secrets-autonomous field fails closed: a malformed non-boolean value disables autonomous binding, which is the safer direction. Secrets are injected into the sandbox subprocess environment only when the skill is activated, and the binding is audited through REDACTED_CONTEXT_KEYS so secret values never appear in logs. This is more granular than the allowed-tools field Anthropic's skill format defines, and it directly addresses the prompt-injection-via-skill attack surface that the skill supply-chain scanner tier (NVIDIA/SkillSpector, sheeki03/tirith, panguard-ai) exists to detect.

The 25 public skills cover a broad surface, and several are non-trivial. The catalog spans research (deep-research, github-deep-research, academic-paper-review, systematic-literature-review, consulting-analysis, data-analysis), content generation (ppt-generation, newsletter-generation, podcast-generation, video-generation, image-generation, music-generation), engineering (code-documentation, frontend-design, web-design-guidelines, vercel-deploy-claimable), and meta-skills (skill-creator, find-skills, bootstrap, surprise-me, claude-to-deerflow). The chart-visualization skill ships 25 reference files for chart types (area, bar, boxplot, column, district-map, dual-axes, fishbone, flow, funnel, histogram, liquid, mind-map, network-graph, organization-chart, path-map, pie, pin-map, radar, sankey, scatter, treemap, venn, violin, word-cloud, spreadsheet) plus a 173-line generate.js script that posts to an AntV visualization API. The deep-research skill is a real four-phase methodology (broad exploration, deep dive, diversity and validation, synthesis check) with temporal-awareness rules that instruct the model to check before forming search queries, rather than a one-line "search the web" instruction.

The make doctor health check is honest and actionable, and it runs without a configured environment. Running uv run python ../scripts/doctor.py from the backend produced a clean checklist: Python 3.12.13, Node.js 24.13.1, pnpm 11.10.0, and uv 0.10.2 all passed. It flagged 2 errors (nginx not installed, config.yaml not found) and 2 warnings (.env and frontend/.env missing), each with a specific fix hint ("Run 'make setup' to create it"). It did not crash, did not produce a traceback, and did not require a configured config.yaml to run. This is the same pattern RAPTOR's doctor command uses, and it is the right default for a tool with this many moving parts.

The Bad

This is a full-stack application, not a skill pack, and the setup barrier is real. DeerFlow runs four cooperating services: Nginx (port 2026), Gateway API (port 8001), Frontend (port 3000), and an optional Provisioner (port 8002). The make setup wizard is interactive and takes about 2 minutes per the README, but it requires an LLM provider choice, API keys, and decisions about sandbox mode, bash access, and file-write tools. The config.example.yaml file is 83,534 bytes (1,600-plus lines of YAML), which is an order of magnitude larger than most agent tool configurations. A user who wants to try a single skill (say, deep-research) still needs to stand up the entire stack or use the TUI mode, which itself requires installing the deerflow-harness[tui] extra and a configured config.yaml with an LLM provider. There is no way to run a skill in isolation the way you can with a Claude Code skill or a standalone MCP server.

Several headline skills depend on ByteDance-ecosystem APIs that most non-Chinese users will not have keys for. The music-generation skill calls MiniMax's music_generation endpoint (model music-2.6-free). The podcast-generation skill supports both Volcengine TTS and MiniMax TTS. The video-generation skill supports both Gemini and MiniMax. The chart-visualization skill defaults to https://antv-studio.alipay.com/api/gpt-vis (an Ant Group/Alipay service). The README's "Coding Plan from ByteDance Volcengine" section recommends Doubao-Seed-2.0-Code, DeepSeek v3.2, and Kimi 2.5. The InfoQuest integration is a BytePlus search and crawling toolset. A user outside the ByteDance/Volcengine ecosystem can use the deep-research, data-analysis, and code-documentation skills with any OpenAI-compatible LLM, but the media-generation skills are effectively gated behind Chinese API providers unless the user wires up Gemini or configures alternative endpoints.

The security notice in the README acknowledges that the agent has high-privilege capabilities and the default deployment is loopback-only, which is a real operational constraint. The README states that DeerFlow has "key high-privilege capabilities including system command execution, resource operations, and business logic invocation" and is "designed by default to be deployed in a local trusted environment (accessible only via 127.0.0.1 loopback interface)." It warns that deploying in untrusted environments without strict security measures (IP allowlist, authentication gateway, network isolation) may lead to "unauthorized illegal invocation" with "system command execution." This is honest, but it means DeerFlow is not safe to expose on a LAN or public cloud without additional hardening. The LocalSandboxProvider disables host bash by default (correct), but the AioSandboxProvider for container isolation requires Docker and a configured sandbox mode. A team that wants to deploy DeerFlow as a shared service needs to treat it as infrastructure, not a tool.

Standard pip install fails because the project uses a uv workspace, and this is not documented prominently enough. The backend/pyproject.toml declares deerflow-harness as a workspace member via [tool.uv.workspace] and [tool.uv.sources]. Running pip install -e ".[dev]" from the backend directory fails with a setuptools package-discovery error because pip cannot resolve the workspace dependency. The correct path is cd backend && uv sync or make setup, which uses uv run throughout. The README does mention uv in the Quick Start, but a developer who defaults to pip (the standard Python workflow) hits an opaque build error before reaching the setup wizard. The pre-commit config also assumes uv (cd backend && uv run ruff check), so the entire toolchain is uv-locked.

The skill-creator and claude-to-deerflow skills are clearly derived from Anthropic's originals, and the provenance is not always attributed. The skill-creator skill is a near-direct adaptation of Anthropic's skill-creator, with DeerFlow-specific additions for the skill_manage tool and sandbox filesystem isolation. The claude-to-deerflow skill references Claude Code's npx skills add install path and the skills.sh registry. Neither skill credits Anthropic's original in its SKILL.md body, though the README's acknowledgments section does thank LangChain and LangGraph. This is not a license issue (both are MIT), but a reader auditing the skill catalog might wonder which skills are original DeerFlow work and which are adapted from upstream.

Smoke Test Results

Tested on a macOS host (aarch64) with Python 3.12.13, Node.js 24.13.1, pnpm 11.10.0, and uv 0.10.2. The repo was shallow-cloned to 58MB. Backend dependencies were installed via uv sync (214 packages). The make doctor health check was run without a configured environment. Skill tests were run from both the repo root and the backend test suite.

Run A. Fresh clone, skill tests only

$ git clone --depth 1 https://github.com/bytedance/deer-flow.git
Cloning into 'deer-flow-gs'... (58MB)

$ /tmp/deerflow-venv/bin/pip install pytest requests
$ /tmp/deerflow-venv/bin/python -m pytest tests/skills/ -v
tests/skills/test_music_generation.py::test_with_lyrics_payload_and_writes PASSED
tests/skills/test_music_generation.py::test_instrumental_sets_flag PASSED
... (48 more)
tests/skills/test_video_generation.py::test_gemini_post_raises_on_http_error PASSED

51 passed in 0.82s PASS

Pass rate: 51 of 51. All root-level skill tests pass with mocked HTTP. No API keys required. The tests assert on real request payloads, headers, error codes, and retry behavior.

Run B. Backend skill tests (with-deps via uv)

$ cd backend && uv sync
Installed 214 packages in 840ms

$ uv run python -m pytest tests/ -k "skill" -q
........................................................................ [ 10%]
........................................................................ [ 21%]
... (670 dots)
...................... [100%]
670 passed, 2 skipped, 6106 deselected in 9.42s PASS

$ uv run python -m pytest --collect-only -q
6776 tests collected in 16.82s PASS

Pass rate: 670 of 672. The 2 skipped tests are integration tests that require an external service (Redis). The 670 passing tests cover the skill parser (YAML frontmatter, allowed-tools, required-secrets, secrets-autonomous), SkillScan (all 18 rule specs, archive extraction, path traversal, executable binary detection), skill storage (local and user-scoped), skill activation middleware (slash activation, autonomous binding, secret injection), and the skill_manage tool (create, edit, patch, delete, write_file, remove_file).

Run C. Doctor health check

$ cd backend && uv run python ../scripts/doctor.py

DeerFlow Health Check
 System Requirements
 Python (3.12.13) PASS
 Node.js (24.13.1) PASS
 pnpm (11.10.0) PASS
 uv (0.10.2) PASS
 nginx FAIL (brew install nginx)

 Configuration
 .env found WARN (Run 'make setup')
 config.yaml found FAIL (Run 'make setup')

Status: 2 error(s), 2 warning(s) PASS (doctor ran without crashing)

Functional pass rate: 3 of 3 exercised. The doctor ran cleanly without a configured environment, reported exactly what was missing, and provided fix hints. The skill tests and backend tests all pass. What could not be exercised: the full agent workflow (sub-agent delegation, sandboxed execution, deep research pipeline) requires a running full-stack instance with an LLM API key and a configured config.yaml.

What the runs tell you

The skills system is production-grade and verifiable on any host with Python 3.12 and uv. The 721 passing skill-related tests (51 root plus 670 backend) cover the parser, the SkillScan scanner, the storage layer, the activation middleware, and every media-generation skill's API integration logic with mocked HTTP. The doctor is honest about what is missing. The limitation is that the headline agent workflow, the thing that makes DeerFlow a "super-agent harness" rather than a skill library, cannot be exercised without a running full-stack instance and an LLM, so it stays at a "partial" functional rating by honest necessity.

Setup Walkthrough

1. Install Python 3.12 or newer, Node.js 22 or newer, pnpm, and uv. On macOS, brew install python@3.12 node pnpm uv. Stock system Python (3.9.6 on older macOS) will not work.
2. Clone the repo: git clone https://github.com/bytedance/deer-flow.git && cd deer-flow.
3. Run make setup from the repo root. This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution and safety preferences (sandbox mode, bash access, file-write tools). It generates config.yaml and writes your keys to .env. Takes about 2 minutes.
4. Run make doctor to verify your setup. It checks system requirements (Python, Node, pnpm, uv, nginx), configuration files (.env, config.yaml), LLM provider, web capabilities, and sandbox mode. Fix any errors it reports before proceeding.
5. Choose your run mode. For the full stack: make dev (local development) or Docker (docker compose -f docker/docker-compose.yml up -d). For the terminal UI only: cd backend && uv pip install 'deerflow-harness[tui]' && deerflow. For headless one-shot: deerflow --print "summarize this repo".
6. To install the Claude Code integration skill only (without running DeerFlow): npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow. This gives you the claude-to-deerflow slash command in Claude Code, which sends tasks to a running DeerFlow instance.

Post-install gotcha: the backend uses a uv workspace, so standard pip install from the backend directory fails with a setuptools package-discovery error. Use uv sync or make setup (which wraps uv run) instead. If you want the media-generation skills (music, video, podcast) to actually produce output, you need API keys for MiniMax, Volcengine, or Gemini, depending on the skill. The chart-visualization skill defaults to the AntV Alipay endpoint unless you set VIS_REQUEST_SERVER to an alternative.

Alternatives

1. anthropics/skills - the official Anthropic skill pack that DeerFlow's skill-creator and claude-to-deerflow skills are adapted from. Prefer it if you want vendor-neutral skills that drop into Claude Code directly, without standing up a full agent platform.
2. gadievron/raptor - a Claude Code security research framework that also runs a native supply-chain scanner (SCA) and a fail-loud sandbox. Prefer RAPTOR if your focus is security research and vulnerability validation; prefer DeerFlow if you want a general-purpose super-agent harness with a broader skills catalog.
3. DeusData/codebase-memory-mcp - an MCP server for persistent codebase memory. Prefer it if you want memory and context management as a protocol-level tool that works across MCP clients, rather than a full agent platform. DeerFlow has its own long-term memory system but it is tightly coupled to the harness.
4. obra/superpowers - the community brainstorming and methodology skill pack. Prefer it if you want lightweight, drop-in skills for creative and planning workflows without the infrastructure overhead of a full-stack agent runtime.