**[English](README.md) | [中文](README_CN.md)**

--- ## ✨ 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](WORKFLOW_GUIDE.md) for the complete 4-level workflow system. --- ## 🚀 Quick Start ### Install CCW ```bash 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](FAQ.md#better-sqlite3-node_module_version-mismatch) for details. ### Choose Your Workflow Level

Level	Command	Use Case
2	`/workflow:lite-plan`	Quick fixes, 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 ```bash # Level 2: Lightweight planning (recommended for most tasks) /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

```text # 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: ```bash 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](https://docs.augmentcode.com/context-services/mcp/overview) | | **Proxy** | [ace-tool (GitHub)](https://github.com/eastxiaodong/ace-tool) |

--- ## 📚 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

```bash # 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**: ```bash # /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 ```bash 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**](WORKFLOW_GUIDE.md) | 4-level workflow system (recommended) | | [**Getting Started**](GETTING_STARTED.md) | 5-minute quick start | | [**Dashboard Guide**](DASHBOARD_GUIDE.md) | Dashboard user guide | | [**FAQ**](FAQ.md) | Common questions | | [**Changelog**](CHANGELOG.md) | Version history |

--- ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Main Workflow (4 Levels) │ │ ⚡ Level 1: lite-lite-lite (instant execution) │ │ 📝 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 --- ## 📦 Project Structure ``` Claude-Code-Workflow/ ├── .claude/ │ ├── agents/ # 22 specialized agents (team-worker, cli-discuss, etc.) │ ├── commands/ # Slash commands (5 categories) │ │ ├── root/ # Root commands (/ccw, /ccw-coordinator) │ │ ├── cli/ # CLI commands (cli-init, codex-review) │ │ ├── issue/ # Issue management (plan, execute, queue) │ │ ├── memory/ # Memory commands (prepare, style-skill-memory) │ │ └── workflow/ # Workflow commands (brainstorm, plan, session) │ └── skills/ # 37 modular skills │ ├── review-code/ # Code review with rule-based analysis │ ├── skill-tuning/ # Skill diagnosis and optimization │ ├── skill-generator/ # Skill scaffolding and generation │ ├── spec-generator/ # Product specification generation │ ├── memory-*/ # Memory management skills │ ├── workflow-*/ # Workflow orchestration skills │ ├── team-*/ # Team coordination skills │ └── ... ├── ccw/ │ ├── src/ # TypeScript source code │ │ ├── commands/ # CLI command implementations │ │ ├── core/ # Core services (a2ui, auth, hooks, routes) │ │ ├── mcp-server/ # MCP server implementation │ │ ├── tools/ # Tool implementations │ │ └── utils/ # Utility functions │ └── frontend/ # React frontend (Terminal Dashboard, Orchestrator) ├── codex-lens/ # Local semantic code search engine └── docs/ # Documentation ``` --- ## 🎼 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. **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. **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 and fullscreen mode. --- ## 🤝 Contributing

--- ## 📄 License

MIT License - see [LICENSE](LICENSE)