Ddflow

What ddflow does

The ddflow MCP server provides a work-queue kernel for projects built with AI coding agents. Work is organized into phases and tasks, with dependencies and declared file globs. A task can receive a lease and an isolated Git worktree, allowing independent tasks to run without editing the same checkout. Tasks that declare overlapping files are refused rather than silently combined.

The system does not write the project's application code. Instead, it adds and manages its own configuration, rules, hooks, and event history. Decisions, lessons, research verdicts, bugs, prompts, and task activity are recorded in an append-only log under .ddflow/events/. That history is committed with the repository and can be used to reconstruct project decisions.

How it works

A project moves through a queue of dependent work. Tasks that are ready can be claimed, while blocked tasks remain pending until their prerequisites are satisfied. Claimed work is performed in the returned Git worktree, then checked through a configured gate pipeline before it is merged and completed.

The gate model records a check that could not run as unavailable; it is not treated as passed. The documented rules also require a reviewer from a different model family than the author and require a regression test that failed first before a bug can close. If an agent stops unexpectedly, recovery can find orphaned worktrees without deleting their contents.

The same implementation is available through the ddflow command-line interface and MCP tools. The README lists compatibility with Claude Code, Gemini CLI, Codex, Copilot, Cursor, Kimi, opencode, Aider, CI jobs, Makefiles, and terminal users. The MCP listing provided for this entry includes configuration, upgrade planning, and project adoption tools.

Setup and configuration

Install the package from the Git repository with:

uv tool install git+https://github.com/delian/ddflow-mcp

It is not published on PyPI according to the project documentation. From the project root, run ddflow adopt --agents claude with the appropriate agent name. Adoption writes the .ddflow/ directory, registers the MCP server, adds a commit hook, and writes a rules block in AGENTS.md; the agent session should then be restarted.

Use ddflow_configure to apply ddflow config --set or --append-toml changes. The repository stores shared settings in .ddflow/, while .ddflow/local/ is intended for ignored, local-only configuration. Gate commands and other workflow behavior are configurable rather than fixed. Core dependencies are Python 3, Git, Jinja2, and tomlkit. Optional search and retrieval extras exist, but a check requiring an absent extra is recorded as unavailable.

Tools and capabilities

The ddflow MCP server exposes these documented tools:

• ddflow_configure applies configuration changes using ddflow config --set or --append-toml.
• ddflow_upgrade reads the ddflow upgrade plan without making changes.
• ddflow_setup runs ddflow adopt to onboard a project.

After adoption, the broader CLI workflow can import existing plans, configure gates, add phases and tasks, inspect the queue, recover orphaned work, and run diagnostics. The README describes those operations as part of the same implementation, but they are not included in the MCP tool list supplied for this listing.

Limitations and notes

The project is not an autonomous coding agent and does not create application code. Adoption changes the repository and installs a tool, registers an MCP server, and writes project files, so the user should agree before it runs. The upgrade tool is read-only, while setup and configuration can write files or settings.

Exit status 2 means that an operation could not run or had nothing to do; it must not be interpreted as success. A missing optional dependency does not allow its associated gate to pass. Network transport through the MCP SDK is described as declared but not yet used, so this listing should be treated as a local CLI/MCP integration rather than evidence of a network service.