---
## β¨ 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 |
|---|
| 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
```bash
# 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
---
## π 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, 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](LICENSE)
