flow-claude 1.0.0.post1

Claude Code UI-native autonomous development system with git-first architecture

Flow-Claude

---

Flow-Claude: Git-native parallel task orchestration for Claude Code.

Flow-Claude extends Claude Code with git-driven task orchestration. Break down large features into parallel subtasks, execute them simultaneously, and merge results automatically.

---

Key feature and Benfits

Flow+Claude subagent with GitHub as the version control and information hub (sinlge source of truth).

Claude automatically generates plans and creates both plan branches and task branches:

The plan branch defines the overall workflow and updates automatically whenever a task is completed.

Each task branch is used to execute an individual task. Tasks can run in parallel using Git worktrees.

This setup ensures smooth automation, parallel task execution, and continuous synchronization between planning and execution stages.

Works seamlessly within Claude Code UI

Related paper

To be a conributor

submit an github issue (link) and contact team via [e-mail] and discord xxx

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

---

Workflow

graph TD
  A["Your Request"] --> B["Orchestrator"]
  B --> C["Worker 1 (task/001)"]
  B --> D["Worker 2 (task/002)"]
  B --> E["Worker 3 (task/003)"]
  C --> F["flow branch (merged results)"]
  D --> F
  E --> F

---

Installation

Prerequisites

• Python 3.10+
• Git
• Node.js 18+ (LTS recommended)
• npm 9+ or equivalent package manager
• Windows users: See Windows Installation Guide for special instructions

IMPORTANT: Claude Code must be installed first:

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

See Claude Code Setup for more details.

---

Install From PyPI

pip install flow-claude

Install From Source

git clone https://github.com/a5507203/flow-claude.git
cd flow-claude
pip install -e .

Verify Installation:

flow --help

Expected output:

Usage: flow [OPTIONS]

  Initialize Flow-Claude for Claude Code UI.

  Creates .claude/ directory structure with skills, commands, and agents.
  Run once per project, then use Claude Code UI for development.

Options:
  --help  Show this message and exit.

---

Initialize Your Project

Warning: For existing projects, backup your .claude/ directory and CLAUDE.md first, flow will overwrite them.

Navigate to your git repository and initialize Flow-Claude:

Linux / macOS

cd /path/to/your/project
flow

Windows

Option 1: Using Python Module (Works Immediately)

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

Option 2: Using flow Command (Requires PATH Setup)

# Find your Python Scripts directory
python -c "import os, sys; print(os.path.join(sys.prefix, 'Scripts'))"

# Add to PATH (PowerShell - current session)
$env:PATH += ";C:\Users\YourUsername\AppData\Roaming\Python\Python3XX\Scripts"

# Or add permanently via System Environment Variables 
# Step1: Press `Win + R`
# Step2: Type `sysdm.cpl`
# Step3: Switch to `Advanced`
# Step4: Clip `Environment Variables` to add

Then run:

flow

---

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

Directory Structure

your-project/
├── .claude/        # Flow-Claude skills, commands, agents, settings
├── .worktrees/     # Git worktrees for worker branches (auto-created, ignored by git)
├── CLAUDE.md       # Flow-Claude instructions prepended to the repo
|-- Original Projects Content...

---

Example Usage

Flow-Claude can orchestrate large features with parallel workers or keep things simple when the request is tiny.

Usage Workflow

# Initialize
cd my-project
flow

# Open Claude Code
claude --dangerously-skip-permissions

# Ask:
"Read the SILLs, then Build a REST API for blog posts with CRUD operations"

# Flow-Claude creates:
# - plan/session-20250121-143000 (execution plan)
# - task/001-create-post-model
# - task/002-implement-crud-service
# - task/003-create-api-endpoints
# Workers execute in parallel, merge to flow branch

Flow-Claude will:

1. Plan - Break the request into parallel tasks (model, CRUD service, API endpoints).
2. Execute - Launch workers for the ready tasks, each in its own worktree.
3. Merge - Merge completed task branches back into flow and update the plan.

Small Task Case

When the request is clearly a quick fix (e.g., “Update README typos” or “Bump a config flag”), the main orchestrator handles it directly instead of launching workers:

• Evaluate the request scope; if it only needs one short change, skip plan/task branch creation.
• Work directly on the flow branch (or a lightweight scratch branch) and apply the change.
• Report back to the user with the diff/summary just like a worker would.

Git Branch Structure

main/master (production)
    ↑
flow (development base)
    ├── plan/session-* (execution plans)
    ├── task/001-*
    ├── task/002-*
    └── task/003-*

Commands

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

---

MCP Servers and AgentSkills

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

---

Hooks Setup

Get notified when Claude needs attention or completes tasks - useful when running AI in background.

1. Install notification script:

npx claude-code-templates@latest --hook=automation/simple-notifications --yes

Then delete the postToolUse hook added by this command (we only need the notification script it installs).

2. Add hooks via /hooks command:

Hook Type	Command
Stop (task done)	if command -v osascript >/dev/null 2>&1; then osascript -e 'display notification "Task completed successfully" with title "✅ Claude Code Done"'; elif command -v notify-send >/dev/null 2>&1; then notify-send '✅ Claude Code' 'Task completed successfully'; fi
Notification (action needed)	if command -v osascript >/dev/null 2>&1; then osascript -e 'display notification "Claude Code needs your input or approval!" with title "🛑 Action Required"'; elif command -v notify-send >/dev/null 2>&1; then notify-send '🛑 Claude Code' 'Action or permission required!'; fi

Works on macOS (osascript) and Linux (notify-send).

---

License

MIT License - see LICENSE for details.

Support

• GitHub Issues

---

Ready to supercharge your development?

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