DeerFlow: a super-agent harness for long-running work

Everything worth knowing about bytedance/deer-flow: an open-source application and runtime for coordinating agents, tools, memory, and sandboxes on tasks that can run from minutes to hours.

---

What DeerFlow is

DeerFlow 2.0 is an open-source agent harness from ByteDance. It presents itself as a foundation for research, coding, and deliverable creation; it brings together subagents, long-term memory, sandboxes, tools, extensible skills, and a messaging gateway.

The documentation separates two layers: DeerFlow Harness, the SDK and runtime for building agent systems, and DeerFlow App, the reference application for deploying and operating them. It isn’t a language model or a guarantee of autonomy: it requires configuring model providers, permissions, and tools.

The origin: from deep research to a 2.0 rewrite

The repository was created on May 7, 2025 under the bytedance organization and is distributed under the MIT license. The initial line was described as a community deep-research framework; version 2.0 was rewritten from scratch, and the README states it shares no code with v1, which remains available on the main-1.x branch.

The conceptual name change matters: the current project isn’t limited to searching sources. Its proposal is to provide reusable infrastructure for multi-step tasks, with execution, files, planning, and communication, rather than an isolated conversation interface.

Philosophy and principles

• Long-range work, not a single response: the harness tries to preserve state, split tasks, and recover context when an assignment outgrows a brief interaction.
• Substitutable components: models, tools, MCP servers, skills, and sandbox providers are configured rather than locked to a single provider.

• Isolation and permission control: sandboxes let agent work run; the documentation warns the local provider doesn’t protect the host and that host Bash access should stay disabled except in trusted cases.

• Operable application: beyond the runtime, it includes a web interface, streaming, artifacts, threads, and messaging channels for using an agent workflow outside a one-off prototype.

How it works

The documented architecture places Nginx as the entry point, a Next.js/React interface, and a FastAPI gateway that integrates the LangGraph runtime. The main agent coordinates tools, files, attachments, memory, planning, and subagents; results can appear as streaming events and artifacts.

A user opens a thread, picks a model, and states a request. For a broad task, they can enable Plan Mode, which keeps the task list visible. Skills are selected from the interface or invoked with /skill-name; for example, the documentation shows /data-analysis analyze uploads/foo.csv to analyze an uploaded CSV.

The working directory, models, memory, sandbox providers, tools, and skills are mainly declared in config.yaml; extensions_config.json controls MCP servers and extension activation.

Official and semi-official status

DeerFlow is an official project of the ByteDance organization on GitHub, and its landing page links to deerflow.tech. The repository offers a documented integration for Claude Code via the claude-to-deerflow skill, but no evidence was found that it’s part of an official Anthropic marketplace or that any provider certifies the product.

Its verifiable status is therefore that of an open project maintained by ByteDance, with integrations published by the project itself. Its broad GitHub adoption doesn’t amount to a formal standard designation.

The ecosystem

Sibling project and official extensions

• deer-flow/llm-space appears in the README as a sibling project. It presents itself as a desktop app for prototyping agent ideas, inspecting steps, reproducing failures, and evaluating performance.
• The core supports MCP servers, Python extensions, and messaging channels; the documentation and repository tree include integration with Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, WeCom, GitHub, and Buzz.

• The official claude-to-deerflow skill connects Claude Code to a DeerFlow instance via npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow.

Forks, ports, and community documentation

• stophobia/deerflow2.0-enhanced is described as a Chinese localization with new skills; it recorded 677 stars and 128 forks during this investigation.
• coolclaws/deerflow-book, with 678 stars and 140 forks when checked, is a community source-code analysis, not an official distribution.
• hougithub2018/deer-flow-windows adapts the project to Windows 10/11 without Docker or Nginx and recorded 61 stars and 12 forks.
• Among the highest-starred forks returned by the API are chmod777john/deer-flow-deploy (36), mssnzxm/deer-flow2 (16), and cyl6/deer-flow_2 (14). They’re classified as forks: their descriptions aren’t enough to treat them as ByteDance-maintained substitutes.

No direct, verifiable inclusion in a curated awesome-* list was recovered. No official DeerFlow package on npm or PyPI was identified in the direct queries performed either; this is a search limit, not proof of global nonexistence.

Repo numbers

Measured: August 17, 2026, GitHub API.

Metric	Value
Stars	80,155
Forks	10,979
Real subscribers	332
Open issues and pull requests, combined field	940
Primary language	Python
License	MIT
Created	May 7, 2025
Last recorded push	August 17, 2026
Release published by the API	None recovered

The top contributors returned by the API’s first page were MagicCube (610 contributions), hetaoBackend (258), WillemJiang (232), henry-byted (203), and LofiSu (100). GitHub’s open_issues_count field may include open pull requests, so 940 doesn’t represent issues exclusively. Also, watchers_count mirrors stars in the general response; that’s why subscribers_count is reported as the real subscriber count.

How to contribute

The contribution guide recommends Docker; for the alternative local development path, it asks for Node.js 22 or later, pnpm, uv, and Nginx. The documented flow is: create a branch, format the backend with make format, format the frontend with pnpm format:write, run the relevant tests, and open a pull request.

Checks include make test and make test-live in backend, plus make test and make test-e2e in frontend. Live tests need config.yaml and real credentials, so they can incur cost and create external resources. The pull request template requires declaring what AI assistance was used, how it was used, and that there was human review.

Quick-start guide

Installation and first run

The project’s recommended path is:

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup
make doctor

make setup is a wizard for choosing the model provider, search, and sandbox options; it generates a minimal configuration. The documentation requires Python 3.12 or later, Node.js 22 or later, pnpm, uv, and Nginx for the local path.

To start with containers:

make docker-init
make docker-start
make docker-logs

The application opens at http://localhost:2026; make docker-stop stops it.

Common workflows

1. Extensive research or creation: open a thread, pick a model, describe the desired output, and enable Plan Mode if it requires three or more steps; the task list stays visible during the work.
2. Analyzing a file: upload the CSV and write /data-analysis analyze uploads/foo.csv. Attachments are saved under /mnt/user-data/uploads/ and results can end up as artifacts.

3. Using third-party tools: define a server in extensions_config.json and enable it. For example, a stdio-type MCP server can declare command, args, and enabled.
4. Connecting Claude Code: with DeerFlow running, install the claude-to-deerflow skill and use /claude-to-deerflow inside Claude Code.

Essential configuration

• config.yaml: models, keys via environment variables, tools, memory, and sandbox.
• .env: credentials the setup wizard saves outside the main configuration file.
• extensions_config.json: MCP servers and enabled state for extensions and skills.
• DEER_FLOW_CONFIG_PATH: lets you use a config.yaml located at another path.
• DEERFLOW_URL / DEERFLOW_GATEWAY_URL: optional variables to point the Claude Code integration at another instance.

Common pitfalls and fixes

• The local sandbox doesn’t isolate the host. Keep allow_host_bash: false and use an isolated provider for multi-user or production scenarios.
• Docker publishes to 127.0.0.1 by default. Before setting BIND_HOST=0.0.0.0, the guide advises configuring authentication, HTTPS, and network controls; create the admin at /setup first.
• On Linux, a permission error against the Docker socket is resolved by adding the user to the docker group, starting a new group session, and verifying with docker ps.
• On a Docker network, a service shouldn’t use localhost to reach another container: it should use the service name, like http://gateway:8001.

Integrations and migration

The interface lets you manage MCP; configuration changes are normally detected without a restart via the file’s modification date. The project also exposes an embedded Python client and a documented Claude Code integration.

DeerFlow 2.0 shares no code with v1, and the README offers no general procedure for migrating v1 projects to 2.0. For 2.x configurations there’s make config-upgrade; migrating DeerMem memory to Markdown facts is documented as one-way, and it’s worth backing up before upgrading a persistent deployment.

How the community received it

The recoverable external signal is uneven. On Hacker News, several low-interaction direct submissions were found: thread 43960205, posted by blacktulip, reached 4 points and 0 comments; thread 47546059, from udayan_w, also reached 4 points and 0 comments. These submissions establish reach, not an independent review or consensus.

In thread 47573623, with 3 points and 1 comment, the author cnrd themselves questioned the pattern of using agents to install agents; since it comes from the submitter, it should be read as an individual reservation, not an external evaluation. In a thread about multi-agent systems, akrylov wrote they hadn’t tried DeerFlow 2.0, found the community showcase unconvincing, and asked that multi-agent frameworks demonstrate consistently beating single agents. Thread 48280604 had 6 points and 3 comments; it’s an attributed methodological objection, not a comparative evaluation.

As an audiovisual resource, WorldofAI published a DeerFlow walkthrough oriented toward local execution, with a title presenting it as a research agent; the page showed 25,909 views when recovered. The podcast Awesome Agents Podcast described DeerFlow 2.0’s engineering as impressive, but not as a ready-to-use solution; that’s that show’s editorial assessment, not an independent verdict.

No verifiable X posts were recovered due to the required login. Product Hunt presented an anti-bot verification, and direct Reddit queries returned no extractable threads; these limits don’t support claiming an absence of conversation.

DeerFlow versus other approaches

Approach	Verifiable relationship	Limit of the comparison
DeerFlow v1	The main-1.x branch preserves the previous line.	DeerFlow 2.0 was rewritten from scratch; no general migration guide was recovered.
deer-flow/llm-space	The README calls it a sibling project for agent prototyping and inspection.	It’s a complementary desktop app, not the DeerFlow runtime.
stophobia/deerflow2.0-enhanced	It declares Chinese localization and additional skills.	It’s a community adaptation, not an official edition.

Broad functional comparisons with other agent harnesses aren’t included because the recovered sources don’t support an equivalent, verifiable technical matrix.

Use cases and who this repository can help

• Research, analysis, or content teams can turn an extensive task into a thread with a plan, skills, and artifacts, keeping files and results in the workspace.
• Developers integrating agents into their own application can use the Harness, the Python client, configurable models, and MCP to connect existing tools without locking into a single model provider.
• Operators of an internal instance can combine messaging channels, authentication controls, and a non-local sandbox to offer assisted workflows, as long as they review MCP permissions and deployment conditions.
• Claude Code users can hand off a task to a DeerFlow instance with the official skill, when they need a process that preserves threads, plan, and artifacts outside the editor session.

Resources

• Repository: https://github.com/bytedance/deer-flow
• Documentation and installation: https://deerflow.tech/en/docs
• Application configuration: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/application/configuration.mdx
• Official skills and Claude Code integration: https://github.com/bytedance/deer-flow#claude-code-integration
• Sibling project: https://github.com/deer-flow/llm-space
• Video: https://www.youtube.com/watch?v=1yl6e4TP-ss
• HN discussions: https://news.ycombinator.com/item?id=43960205, https://news.ycombinator.com/item?id=47546059, https://news.ycombinator.com/item?id=47573623, https://news.ycombinator.com/item?id=48280604

---

Note: this article combines the repository, official documentation, the GitHub API, Hacker News, and media resources retrieved on August 17, 2026. Figures change over time.