CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a customized offline deployment of DeerFlow — a LangGraph-based AI super agent platform. The repo contains two sub-projects:

offline-backend-20260512/backend/ — Python backend (FastAPI Gateway + LangGraph agent runtime)
frontend-web/ — Vite + React 19 frontend (TypeScript, pnpm)

Managed together via shell scripts in scripts/.

Commands

Full Application (from repo root)

./scripts/start-all.sh    # Start backend + frontend as background daemons
./scripts/stop-all.sh     # Stop both
./scripts/restart-all.sh  # Restart both
./scripts/status.sh       # Check running status

Logs and PID files are written to .runtime/logs/ and .runtime/pids/.

Backend Only (from `offline-backend-20260512/backend/`)

make install    # Install Python dependencies (uv)
make dev        # Run Gateway API with hot-reload on port 8001
make gateway    # Run Gateway API without reload
make test       # Run all tests: PYTHONPATH=. uv run pytest tests/ -v
make lint       # Lint with ruff
make format     # Format with ruff

Run a single test file:

PYTHONPATH=. uv run pytest tests/test_<feature>.py -v

Frontend Only (from `frontend-web/`)

pnpm install    # Install dependencies
pnpm dev        # Start Vite dev server on port 5174
pnpm build      # Production build
pnpm typecheck  # TypeScript type checking (tsc --noEmit)

Service Ports

Service	Port	Notes
Backend (Gateway API)	8001	FastAPI + LangGraph runtime
Frontend (Vite)	5174	React SPA

Frontend connects to backend via env vars VITE_BACKEND_BASE_URL and VITE_LANGGRAPH_BASE_URL (injected by scripts/start-frontend.sh).

Architecture

Backend

The backend (offline-backend-20260512/backend/) is split into two layers:

packages/harness/deerflow/ — publishable agent framework (deerflow.* imports): LangGraph lead agent, middleware chain, sandbox, tools, MCP, memory, models, skills. Never imports from app.*.
app/ — application layer (app.* imports): FastAPI Gateway routers, IM channel integrations (Feishu, Slack, Telegram, DingTalk).

The Lead Agent (deerflow/agents/lead_agent/) is the single LangGraph graph entry point. It wraps a middleware chain (~18 middlewares assembled in strict order) around LLM calls, handling: thread isolation, sandbox lifecycle, uploads, memory, plan mode, vision, subagent delegation, and loop detection.

Middleware order matters — middlewares are appended in a fixed sequence; ClarificationMiddleware must always be last. See offline-backend-20260512/backend/CLAUDE.md for the full ordered list.

Harness → App import firewall is enforced by tests/test_harness_boundary.py (runs in CI).

Frontend

The frontend (frontend-web/) is a React 19 + Vite SPA:

Routing: React Router v7; top-level routes in src/pages/PageRoutes.tsx, workspace sub-routes in src/pages/WorkspaceRoutes.tsx
Pages: ChatPage (thread chat), AgentChatPage (custom agent chat), AgentsPage/NewAgentPage (agent management), ScheduledTasksPage/ScheduledTaskRunDetailPage (scheduled tasks)
State: TanStack Query for server state, context providers (SubtasksProvider, ArtifactsProvider, PromptInputProvider) scoped to WorkspaceRoutes
LLM streaming: @langchain/langgraph-sdk streams messages from the backend via SSE
UI: Radix UI primitives + TailwindCSS v4 + shadcn-style components in src/components/ui/
Shims: src/shims/ provides next/link and next/navigation polyfills (original code was Next.js)

Configuration

Backend config lives in offline-backend-20260512/backend/config.yaml. Values starting with $ resolve as environment variables (e.g., $OPENAI_API_KEY). MCP servers and skills are configured in extensions_config.json in the same directory.

Detailed Backend Reference

The backend has its own comprehensive documentation at:

offline-backend-20260512/backend/CLAUDE.md — architecture, middleware chain, all API routes, config schema, sandbox/memory/subagent systems
offline-backend-20260512/backend/README.md — setup guide, technology stack

4.3 KiB Raw Blame History