How to Contribute to Deer-Flow: A Complete Developer Guide

To contribute to deer-flow, clone the ByteDance repository, initialize the Docker development environment with make docker-init, create a feature branch, and submit a pull request after verifying your changes with uv run pytest and pnpm test.

DeerFlow is ByteDance's open-source super-agent harness that coordinates sub-agents, memory, and sandboxed execution. Learning how to contribute to deer-flow requires understanding its dual development environment—Docker-based or local—and its standardized Git workflow for adding skills, fixing bugs, or extending the agent architecture.

Setting Up Your Deer-Flow Development Environment

DeerFlow supports two development modes. The Docker-based environment is recommended for consistency, while local development offers faster iteration for experienced contributors.

Docker-Based Development (Recommended)

The Docker setup orchestrates nginx, frontend, gateway API, and the LangGraph server through a unified compose file.

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make config          # Copies config.example.yaml and extensions_config.example.json

make docker-init     # Builds images and installs backend (uv) + frontend (pnpm) deps

make docker-start    # Starts nginx (port 2026), frontend (3000), API (8001), LangGraph (2024)

The architecture is defined in docker/docker-compose-dev.yaml, which wires the reverse proxy to three backends: the React/Next.js frontend, the Gateway API for skill loading and file uploads, and the LangGraph server for agent graph execution.

Local Development Stack

For local development, ensure you have Node 22+, pnpm, uv, and nginx installed.

make check      # Verifies all system dependencies

make install    # Installs backend and frontend dependencies

make dev        # Starts all services with hot-reload enabled

Hot-reload is active for both the Python backend and the TypeScript frontend, allowing immediate feedback during development.

Understanding the Deer-Flow Architecture

Before contributing, familiarize yourself with the system's core components as implemented in the source code:

• Nginx (port 2026): Routes traffic to three backends defined in the Docker compose configuration
• Frontend (port 3000): React/Next.js application configured in frontend/next.config.js with API rewrites to the gateway
• Gateway API (port 8001): Orchestrates HTTP calls, skill loading, and file uploads
• LangGraph Server (port 2024): Runs the agent graph, spawns sub-agents, and executes tools in sandboxed Docker containers

Sandbox execution runs in isolated containers managed by the provisioner service, with optional Kubernetes support via the provisioner kubeconfig handling. Long-term memory and skill loading persist under backend/src/memory/ and skills/ respectively.

The Deer-Flow Contribution Workflow

Creating a Feature Branch

Start by branching from main with a descriptive name:

git checkout -b feature/your-feature-name

Making Changes with Hot-Reload

Whether using Docker or local development, hot-reload is enabled. For example, adding a new skill requires only dropping a SKILL.md file into skills/custom/your-skill/—the backend automatically discovers it at runtime via the loader in backend/src/skills/loader.py.

Running Tests Locally

Verify your changes before committing:

# Backend tests (Python/UV + Pytest)

cd backend
uv run pytest

# Frontend tests (PNPM)

cd ../frontend
pnpm test

These commands mirror the CI pipeline defined in .github/workflows/backend-unit-tests.yml.

Submitting Your Pull Request

Commit using conventional message format:

git add .
git commit -m "feat: add custom skill for data-visualisation"
git push origin feature/your-feature-name

Open a Pull Request on GitHub. CI automatically runs:

• Python linting and formatting (ruff) configured in backend/pyproject.toml
• TypeScript linting (eslint) and prettier defined in frontend/eslint.config.js and frontend/prettier.config.js
• Regression tests including Docker sandbox detection and provisioner kubeconfig handling

Code Examples for Common Contributions

Adding a New Skill

Skills are loaded dynamically from the filesystem. The loader implementation in backend/src/skills/loader.py reads SKILL.md files:

# Simplified from backend/src/skills/loader.py

def load_skill(name: str):
    skill_path = Path("/mnt/skills") / name / "SKILL.md"
    if skill_path.is_file():
        return skill_path.read_text()
    raise FileNotFoundError(f"Skill {name} not found")

To contribute a skill, create skills/custom/my-skill/SKILL.md with your agent instructions. No code changes are required for registration.

Updating a Frontend Component

The frontend uses React with Next.js. Configuration for API routing is in frontend/next.config.js:

// frontend/components/SkillCard.tsx
export const SkillCard = ({title, description}: {title: string; description: string}) => (
  <div className="card">
    <h3>{title}</h3>
    <p>{description}</p>
  </div>
);

Run pnpm dev to see changes instantly via hot-reload.

Using the Embedded Client

For integration testing or external tooling, use the embedded client:

from src.client import DeerFlowClient

client = DeerFlowClient()
resp = client.chat("Generate a slide deck about quantum computing")
print(resp["content"])

The client implementation is located in backend/src/client.py.

Key Files Every Contributor Should Know

File	Role
CONTRIBUTING.md	Detailed Docker/local dev setup, workflow, and branch/PR guidelines
README.md	High-level project description, quick-start commands, architecture overview
Makefile	Central entry point for all developer commands (make docker-init, make dev, make check)
docker/docker-compose-dev.yaml	Docker Compose definition wiring nginx, frontend, API, LangGraph, and provisioner
backend/src/client.py	Embedded Python client for tests and external integrations
backend/src/skills/loader.py	Runtime loader for Markdown skill definitions
frontend/next.config.js	Next.js configuration including API rewrites to the gateway
.github/workflows/backend-unit-tests.yml	CI pipeline running backend regression tests and linting
backend/CLAUDE.md	In-depth architectural explanation of agents, sub-agents, and sandbox execution

Summary

• DeerFlow is ByteDance's super-agent harness requiring contributors to understand its Docker-based or local development environments.
• Setup involves cloning the repository, running make config and either make docker-init (recommended) or make install for local development.
• Architecture consists of nginx routing to three backends: the React frontend (port 3000), Gateway API (port 8001), and LangGraph server (port 2024).
• Workflow follows standard Git practices: feature branches, hot-reload development, testing with uv run pytest and pnpm test, and PR submission with conventional commits.
• Key files include CONTRIBUTING.md, Makefile, docker/docker-compose-dev.yaml, and backend/src/skills/loader.py for skill contributions.

Frequently Asked Questions

What development environment does deer-flow recommend for new contributors?

The Docker-based development environment is recommended for consistency across all contributors. Running make docker-init builds the necessary images and installs dependencies using uv for Python and pnpm for Node.js, while make docker-start launches nginx, the frontend, Gateway API, and LangGraph server with proper networking configured in docker/docker-compose-dev.yaml.

How do I run tests before submitting a contribution to deer-flow?

You must run both backend and frontend test suites to ensure CI compliance. For the backend, navigate to the backend directory and execute uv run pytest, which runs the Python test suite using the same configuration as the CI pipeline defined in .github/workflows/backend-unit-tests.yml. For the frontend, run pnpm test in the frontend directory to verify TypeScript components.

Where should I place new skills when contributing to deer-flow?

New skills belong in the skills/ directory, typically under skills/custom/your-skill-name/SKILL.md. The backend automatically discovers these at runtime through the loader implemented in backend/src/skills/loader.py, which reads the Markdown files without requiring additional registration code or configuration changes.

What commit message format does deer-flow require?

DeerFlow follows the Conventional Commits specification. Use structured prefixes like feat: for new features, fix: for bug fixes, or docs: for documentation changes. For example, git commit -m "feat: add data-visualisation skill for slide deck generation" meets the project's requirements and helps automate changelog generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}