flow-claude

Flow-Claude (Flow for Claude Code)

Flow-Claude is for Claude Code users working on long development tasks.

• Break down requirements into parallel tasks,
• execute them simultaneously without stopping,
• auto-commit every change to Git,
• and merge results automatically.

Related Paper

Niu, B., Song, Y., Lian, K., Shen, Y., Yao, Y., Zhang, K., & Liu, T. Flow: Modularized Agentic Workflow Automation. ICLR 2025

Paper PDF

Design Principle

We design Flow-Claude as a lightweight tool that lives within the Claude CLI. As the Claude code model evolves, the benefits of the framework will also continue to grow.

The framework itself should not become a blocker for future updates of the Claude model. Therefore our primary focus is communication efficiency and parallelism with minimum constraints.

Every new design should smoothly support the Claude CLI.

Contributing

Submit a GitHub issue or contact yu.yao@sydney.edu.au

Installation

Prerequisites

Claude Code must be installed first:

npm install -g @anthropic-ai/claude-code

See Claude Code Setup for more details.

---

Install Flow-Claude From PyPI

pip install flow-claude

Verify Installation:

flow --help

On Windows, if flow is not in your PATH, use:

python -m flow_claude.commands.flow_cli --help

---

Quick Start and Tips

1. Initialize Your Project

Navigate to your git repository and initialize Flow-Claude:

Linux / macOS

cd /path/to/your/project
flow

Windows

On Windows, if flow is not in your PATH, use:

cd /path/to/your/project
python -m flow_claude.commands.flow_cli

---

What happens during initialization:

• Creates flow branch from your main branch
• Creates .claude/ directory with skills, commands, agents
• Creates/updates CLAUDE.md with Flow-Claude instructions
• Commits all changes to flow branch

2. Launch Claude Code

claude

If you want to avoid frequent permission approval, use:

claude --dangerously-skip-permissions

3. Prompt Claude to use Flow-Claude

Because the current Claude model does not reliably invoke Skills automatically, you need to append a reminder at the end of your prompt.

For example:

Build a REST API for blog posts with CRUD operations. Remember to use your SKILLs.

4. Resume

When you return to a project after a break or session interruption, prompt Claude to understand the current state before continuing.

Step 1: Use the resume command to restore your previous conversation:

/resume

Select the past conversation from the list.

Step 2: Prompt Claude to check the current state and continue. For example:

Check the current plan and task branch status, then continue the unfinished task. Remember to use Skills.

---

5. Commit Manual Changes

If you make local changes on the flow branch and want workers to use them, commit your changes first:

git add . && git commit -m "Your commit message"

Workers pull from the flow branch, so uncommitted changes won't be visible to them.

6. Delete Unwanted Branches

After a plan is finished and all tasks passed, you may want to clean up the created branches. Use a prompt like:

Delete the plan/<plan-name> branch and all its related task branches.

For example: Delete the plan/blog-api-crud branch and all its related task branches.

---

6. Commands

Command	Description
\auto	Toggle autonomous mode (ON = no approval needed)
\parallel N	Set max parallel workers (1-10, default: 3)

---

MCP Servers and Skills

The main agent can automatically determine which MCP tools and agent skills the worker agents require.

MCP Servers Install

Flow-Claude uses MCP in the same way as Claude Code, except that MCP servers must be installed inside your project directory.

For detailed MCP setup instructions, see:

• Claude Code MCP

Example: Adding the Playwright MCP server

claude mcp add playwright -- npx --scope project @playwright/mcp@latest # Run this command inside your project directory

Or manually add to .mcp.json in your project root folder:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Skill Install

Flow-Claude uses Skill in the same way as Claude Code, except that Skill must be added inside your project directory.

For detailed Skill adding instructions, see:

• Claude Code Skill

Example: Creating Skills

• Created as SKILL.md files in specific directories (.claude/skills/)

.claude/skills/processing-pdfs/
└── SKILL.md

---

License

MIT License - see LICENSE for details.

Ready to supercharge your development?

pip install flow-claude && cd your-project && flow