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

> Learn how to contribute to deer-flow! Follow our developer guide to clone the repository, set up the Docker environment, and submit your pull request. Start contributing today.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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.

```bash
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`](https://github.com/bytedance/deer-flow/blob/main/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.

```bash
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`](https://github.com/bytedance/deer-flow/blob/main/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:

```bash
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`](https://github.com/bytedance/deer-flow/blob/main/SKILL.md) file into `skills/custom/your-skill/`—the backend automatically discovers it at runtime via the loader in [`backend/src/skills/loader.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/skills/loader.py).

### Running Tests Locally

Verify your changes before committing:

```bash

# 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`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml).

### Submitting Your Pull Request

Commit using conventional message format:

```bash
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`](https://github.com/bytedance/deer-flow/blob/main/backend/pyproject.toml)
- **TypeScript linting** (`eslint`) and **prettier** defined in [`frontend/eslint.config.js`](https://github.com/bytedance/deer-flow/blob/main/frontend/eslint.config.js) and [`frontend/prettier.config.js`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/skills/loader.py) reads [`SKILL.md`](https://github.com/bytedance/deer-flow/blob/main/SKILL.md) files:

```python

# 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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/frontend/next.config.js):

```tsx
// 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:

```python
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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py).

## Key Files Every Contributor Should Know

| File | Role |
|------|------|
| [`CONTRIBUTING.md`](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md) | Detailed Docker/local dev setup, workflow, and branch/PR guidelines |
| [`README.md`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/docker/docker-compose-dev.yaml) | Docker Compose definition wiring nginx, frontend, API, LangGraph, and provisioner |
| [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py) | Embedded Python client for tests and external integrations |
| [`backend/src/skills/loader.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/skills/loader.py) | Runtime loader for Markdown skill definitions |
| [`frontend/next.config.js`](https://github.com/bytedance/deer-flow/blob/main/frontend/next.config.js) | Next.js configuration including API rewrites to the gateway |
| [`.github/workflows/backend-unit-tests.yml`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml) | CI pipeline running backend regression tests and linting |
| [`backend/CLAUDE.md`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md), `Makefile`, [`docker/docker-compose-dev.yaml`](https://github.com/bytedance/deer-flow/blob/main/docker/docker-compose-dev.yaml), and [`backend/src/skills/loader.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/.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`](https://github.com/bytedance/deer-flow/blob/main/skills/custom/your-skill-name/SKILL.md). The backend automatically discovers these at runtime through the loader implemented in [`backend/src/skills/loader.py`](https://github.com/bytedance/deer-flow/blob/main/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.