Claude-Code-Workflow/README.md

new line new line

English | 中文

---

✨ Key Features

🎯 4-Level Workflows From lite-lite-lite (instant) to brainstorm (multi-role analysis) 🔄 Multi-CLI Orchestration Gemini, Qwen, Codex, Claude - auto-select or manual ⚡ Team Architecture v2 Role-based agents with inner loop execution 🔧 Queue Scheduler Background queue execution service

📦 Workflow Session Commands start/resume/complete/sync sessions 🖥️ Terminal Dashboard Multi-terminal grid with execution monitor 🎨 Orchestrator Editor Template-based workflow visual editing 💬 A2UI Agent-to-User interactive interface

📖 New? See Workflow Guide for the complete 4-level workflow system.

---

🚀 Quick Start

Install CCW

npm install -g claude-code-workflow
ccw install -m Global

Troubleshooting: If you see NODE_MODULE_VERSION mismatch errors for better-sqlite3, run npm rebuild better-sqlite3. See FAQ - Troubleshooting for details.

Choose Your Workflow Level

Level	Command	Use Case
1	/workflow:lite-lite-lite	Quick fixes, config changes
2	/workflow:lite-plan	Clear single-module features
2	/workflow:lite-fix	Bug diagnosis and fix
2	/workflow:multi-cli-plan	Multi-perspective analysis
3	/workflow:plan	Multi-module development
3	/workflow:tdd-plan	Test-driven development
4	/workflow:brainstorm:auto-parallel	New features, architecture design

Workflow Examples

# Level 1: Instant execution
/workflow:lite-lite-lite "Fix typo in README"

# Level 2: Lightweight planning
/workflow:lite-plan "Add JWT authentication"
/workflow:lite-fix "User upload fails with 413 error"

# Level 3: Standard planning with session
/workflow:plan "Implement payment gateway integration"
/workflow:execute

# Level 4: Multi-role brainstorming
/workflow:brainstorm:auto-parallel "Design real-time collaboration system" --count 5
/workflow:plan --session WFS-xxx
/workflow:execute

---

🛠️ CLI Tool Installation

CLI	Description	Official Docs
Gemini	Google AI analysis	google-gemini/gemini-cli
Codex	OpenAI autonomous coding	openai/codex
OpenCode	Open-source multi-model	opencode-ai/opencode
Qwen	Alibaba Qwen-Code	QwenLM/Qwen

---

🎭 Semantic CLI Invocation

Users can semantically specify CLI tools in prompts - the system automatically invokes the corresponding CLI.

Basic Invocation

User Prompt	System Action
"Use Gemini to analyze the auth module"	Auto-invoke gemini CLI for analysis
"Let Codex review this code"	Auto-invoke codex CLI for review
"Ask Qwen about performance optimization"	Auto-invoke qwen CLI for consultation

Multi-CLI Orchestration

Pattern	User Prompt Example
Collaborative	"Use Gemini and Codex to collaboratively analyze security vulnerabilities"
Parallel	"Have Gemini, Codex, and Qwen analyze the architecture in parallel"
Iterative	"Use Gemini to diagnose, then Codex to fix, iterate until resolved"
Pipeline	"Gemini designs the solution, Codex implements, Claude reviews"

📝 More Examples

# Single CLI invocation
User: "Use Gemini to analyze the database query performance"
→ System auto-calls: gemini CLI with analysis task

# Collaborative analysis
User: "Use Gemini and Codex to collaboratively review the authentication flow"
→ System auto-calls: gemini + codex CLIs, synthesizes results

# Parallel multi-perspective
User: "Have all available CLIs analyze this architecture design in parallel"
→ System auto-calls: gemini, codex, qwen in parallel → merged report

# Sequential pipeline
User: "Use Gemini to plan the refactoring, then Codex to implement it"
→ System auto-calls: gemini (plan) → codex (implement) sequentially

Custom CLI Registration

Register any API as a custom CLI via Dashboard interface:

ccw view  # Open Dashboard → Status → API Settings → Add Custom CLI

Field	Example
Name	deepseek
Endpoint	https://api.deepseek.com/v1/chat
API Key	your-api-key

⚙️ Register once, invoke semantically forever - no code changes needed.

---

🔍 ACE Tool Configuration

ACE (Augment Context Engine) provides powerful semantic code search.

Method	Link
Official	Augment MCP Documentation
Proxy	ace-tool (GitHub)

---

📚 CodexLens Local Search

⚠️ In Development: CodexLens is under iterative optimization. Some features may be unstable.

Search Mode	Description
FTS	Full-text search, based on SQLite FTS5
Semantic	Semantic search, using local embedding models
Hybrid	Hybrid search, combining FTS + Semantic + Reranking

📦 Installation

# Enter codex-lens directory
cd codex-lens

# Install dependencies
pip install -e .

# Initialize index
codexlens index /path/to/project

Open Dashboard via ccw view, manage indexes and execute searches in CodexLens Manager.

---

💻 CCW CLI Commands

🌟 Recommended Commands (Main Features)

Command	Description	When to Use
/ccw	Auto workflow orchestrator - analyzes intent, selects workflow level, executes command chain in main process	✅ General tasks, auto workflow selection, quick development
/ccw-coordinator	Smart orchestrator - intelligently recommends command chains, allows manual adjustment, executes via external CLI with state persistence	🔧 Complex multi-step workflows, customizable chains, resumable sessions

Quick Examples:

# /ccw - Auto workflow selection (Main Process)
/ccw "Add user authentication"              # Auto-selects workflow based on intent
/ccw "Fix memory leak in WebSocket"         # Detects bugfix workflow
/ccw "Implement with TDD"                   # Routes to TDD workflow

# /ccw-coordinator - Manual chain orchestration (External CLI)
/ccw-coordinator "Implement OAuth2 system"  # Analyzes → Recommends chain → User confirms → Executes

Key Differences:

Aspect	/ccw	/ccw-coordinator
Execution	Main process (SlashCommand)	External CLI (background tasks)
Selection	Auto intent-based	Smart recommendation + optional adjustment
State	TodoWrite tracking	Persistent state.json
Use Case	General tasks, quick dev	Complex chains, resumable

---

Other CLI Commands

ccw install           # Install workflow files
ccw view              # Open dashboard
ccw cli -p "..."      # Execute CLI tools (Gemini/Qwen/Codex)
ccw upgrade -a        # Upgrade all installations

Dashboard Features

Feature	Description
Session Overview	Track workflow sessions and progress
CodexLens	FTS + Semantic + Hybrid code search
Graph Explorer	Interactive code relationship visualization
CLI Manager	Execution history with session resume

---

📖 Documentation

Document	Description
Workflow Guide	4-level workflow system (recommended)
Getting Started	5-minute quick start
Dashboard Guide	Dashboard user guide
FAQ	Common questions
Changelog	Version history

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Main Workflow (4 Levels)                    │
│  ⚡ Level 1: lite-lite-lite (instant, no artifacts)             │
│  📝 Level 2: lite-plan / lite-fix / multi-cli-plan (→ execute)  │
│  📊 Level 3: plan / tdd-plan / test-fix-gen (session persist)   │
│  🧠 Level 4: brainstorm:auto-parallel → plan → execute          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   Team Architecture v2                          │
│  🤖 team-worker agents with role-spec based execution           │
│  🔄 Inner loop framework for sequential task processing         │
│  📢 Message bus protocol with team coordination                 │
│  🧠 Wisdom accumulation (learnings/decisions/conventions)       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   Queue Scheduler Service                       │
│  ⚙️ Background execution service with API endpoints             │
│  📊 Queue management and unified CLI execution settings         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   Terminal Dashboard & Orchestrator             │
│  🖥️ Multi-terminal grid with execution monitor                  │
│  🎨 Template-based workflow editor with slash commands          │
│  📡 Real-time agent communication via A2UI                      │
└─────────────────────────────────────────────────────────────────┘

Core Principles:

• ⚡ Dependency Analysis solves parallelism - no worktree needed for main workflow
• 🤖 Team Architecture v2 provides unified role-based agent execution with inner loop
• 🔧 Queue Scheduler handles background task execution with unified settings
• 🖥️ Terminal Dashboard provides real-time monitoring and control
• 🎯 Select workflow level based on complexity - avoid over-engineering

---

🎼 Team Cadence Control (Beat Model)

The v2 team architecture introduces an event-driven beat model for efficient orchestration:

Beat Cycle (single beat)
======================================================================
  Event                   Coordinator              Workers
----------------------------------------------------------------------
  callback/resume --> +- handleCallback -+
                      |  mark completed   |
                      |  check pipeline   |
                      +- handleSpawnNext -+
                      |  find ready tasks |
                      |  spawn workers ---+--> [team-worker A] Phase 1-5
                      |  (parallel OK)  --+--> [team-worker B] Phase 1-5
                      +- STOP (idle) -----+         |
                                                     |
  callback <-----------------------------------------+
  (next beat)              SendMessage + TaskUpdate(completed)
======================================================================

  Fast-Advance (skips coordinator for simple linear successors)
======================================================================
  [Worker A] Phase 5 complete
    +- 1 ready task? simple successor? --> spawn team-worker B directly
    +- complex case? --> SendMessage to coordinator
======================================================================

Key Benefits:

• 🎯 Event-driven: Coordinator only wakes when needed (callback/resume)
• ⚡ Fast-advance: Simple successors spawn directly without coordinator roundtrip
• 🔄 Dynamic pipelines: Generated per-task from dependency graph
• 📊 Parallel execution: Independent tasks run concurrently

---

🖥️ Frontend Highlights

Terminal Dashboard

Multi-terminal grid layout with real-time execution monitoring:

┌─────────────────────────────────────────────────────────────────┐
│  Dashboard Toolbar                    [Issues][Queue][Inspector]│
├──────────┬──────────────────────────────────────────────────────┤
│ Session  │  Terminal Grid (tmux-style split panes)              │
│ Groups   │  ┌─────────────────┬─────────────────────────────────┐│
│ ├─ proj1 │  │ Terminal 1      │ Terminal 2                      ││
│ │  └─ cla│  │ $ ccw cli ...   │ $ gemini analyze ...            ││
│ ├─ proj2 │  │                 │                                 ││
│ └─ ...   │  └─────────────────┴─────────────────────────────────┘│
│          │  Execution Monitor Panel (floating)                   │
└──────────┴──────────────────────────────────────────────────────┘

Features:

• 🖥️ Multi-terminal grid with resizable panes
• 📊 Execution monitor with agent list
• 📁 File sidebar for project navigation
• 🎯 Session grouping by project tags
• 🌙 Fullscreen/immersive mode

Orchestrator Editor

Visual workflow template editor with drag-drop:

┌─────────────────────────────────────────────────────────────────┐
│  FlowToolbar                              [Templates][Execute]  │
├────────────┬────────────────────────────────────────┬───────────┤
│ Node       │          Flow Canvas                   │ Property  │
│ Palette    │  ┌──────────┐     ┌──────────┐        │ Panel     │
│ ├─ Prompt  │  │ Prompt   │────▶│ CLI Tool │        │           │
│ ├─ CLI     │  │ Template │     │ Executor │        │ Edit node │
│ ├─ Slash   │  └──────────┘     └──────────┘        │ props     │
│ └─ Flow    │        │                │              │           │
│            │        ▼                ▼              │           │
│            │  ┌──────────────────────────┐         │           │
│            │  │    Slash Command         │         │           │
│            │  │    /workflow:plan        │         │           │
│            │  └──────────────────────────┘         │           │
└────────────┴────────────────────────────────────────┴───────────┘

Features:

• 🎨 React Flow-based visual editing
• 📦 Template library with pre-built workflows
• 🔧 Property panel for node configuration
• ⚡ Slash command integration

Analysis Viewer

Grid layout for analysis sessions with filtering:

┌─────────────────────────────────────────────────────────────────┐
│  Filters: [Type ▼] [Status ▼] [Date Range]    [Fullscreen]     │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Analysis #1     │ │ Analysis #2     │ │ Analysis #3         │ │
│ │ Type: security  │ │ Type: perf      │ │ Type: architecture  │ │
│ │ Status: ✓ done  │ │ Status: ✓ done  │ │ Status: ⏳ running  │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐                        │
│ │ Analysis #4     │ │ Analysis #5     │                        │
│ │ ...             │ │ ...             │                        │
│ └─────────────────┘ └─────────────────┘                        │
└─────────────────────────────────────────────────────────────────┘

---

🤝 Contributing

---

📄 License

MIT License - see LICENSE