- CLI Tools - Unified Execution Framework
- Purpose
-
- Structured CLI tool usage with configuration-driven tool selection, unified prompt templates, and quality-gated execution.
- Configuration
- :
- ~/.claude/cli-tools.json
- (Global, always read at initialization)
- Initialization (Required First Step)
- Before any tool selection or recommendation
- :
- Check if configuration exists in memory:
- If configuration is already in conversation memory → Use it directly
- If NOT in memory → Read the configuration file:
- Read
- (
- file_path
- =
- "~/.claude/cli-tools.json"
- )
- Parse the JSON to understand:
- Available tools and their
- enabled
- status
- Each tool's
- primaryModel
- and
- secondaryModel
- Tags defined for tag-based routing
- Tool types (builtin, cli-wrapper, api-endpoint)
- Use configuration throughout the selection process
- Why
-
- Tools, models, and tags may change. Configuration file is the single source of truth.
- Optimization
-
- Reuse in-memory configuration to avoid redundant file reads.
- Process Flow
- ┌─ USER REQUEST
- │
- ├─ STEP 1: Load Configuration
- │ ├─ Check if configuration exists in conversation memory
- │ └─ If NOT in memory → Read(file_path="~/.claude/cli-tools.json")
- │
- ├─ STEP 2: Understand User Intent
- │ ├─ Parse task type (analysis, implementation, security, etc.)
- │ ├─ Extract required capabilities (tags)
- │ └─ Identify scope (files, modules)
- │
- ├─ STEP 3: Select Tool (based on config)
- │ ├─ Explicit --tool specified?
- │ │ YES → Validate in config → Use it
- │ │ NO → Match tags with enabled tools → Select best match
- │ │ → No match → Use first enabled tool (default)
- │ └─ Get primaryModel from config
- │
- ├─ STEP 4: Build Prompt
- │ └─ Use 6-field template: PURPOSE, TASK, MODE, CONTEXT, EXPECTED, CONSTRAINTS
- │
- ├─ STEP 5: Select Rule Template
- │ ├─ Determine rule from task type
- │ └─ Pass via --rule parameter
- │
- ├─ STEP 6: Execute CLI Command
- │ └─ ccw cli -p "
" --tool --mode --rule - │
- └─ STEP 7: Handle Results
- ├─ On success → Deliver output to user
- └─ On failure → Check secondaryModel or fallback tool
- Configuration Reference
- Configuration File Location
- Path
- :
- ~/.claude/cli-tools.json
- (Global configuration)
- IMPORTANT
-
- Check conversation memory first. Only read file if configuration is not in memory.
- Reading Configuration
- Priority
- Check conversation memory first Loading Options : Option 1 (Preferred): Use in-memory configuration if already loaded in conversation Option 2 (Fallback): Read from file when not in memory
Read configuration file
- cat
- ~/.claude/cli-tools.json
- The configuration defines all available tools with their enabled status, models, and tags.
- Configuration Structure
- The JSON file contains a
- tools
- object where each tool has these fields:
- Field
- Type
- Description
- Example
- enabled
- boolean
- Tool availability status
- true
- or
- false
- primaryModel
- string
- Default model for execution
- "gemini-2.5-pro"
- secondaryModel
- string
- Fallback model on primary failure
- "gemini-2.5-flash"
- tags
- array
- Capability tags for routing
- ["分析", "Debug"]
- type
- string
- Tool type
- "builtin"
- ,
- "cli-wrapper"
- ,
- "api-endpoint"
- Expected Tools (Reference Only)
- Typical tools found in configuration (actual availability determined by reading the file):
- Tool
- Typical Type
- Common Use
- gemini
- builtin
- Analysis, Debug (分析, Debug tags)
- qwen
- builtin
- General coding
- codex
- builtin
- Code review, implementation
- claude
- builtin
- General tasks
- opencode
- builtin
- Open-source model fallback
- Note
-
- Tool availability, models, and tags may differ. Use in-memory configuration or read
- ~/.claude/cli-tools.json
- if not cached.
- Configuration Fields
- enabled
-
- Tool availability (boolean)
- primaryModel
-
- Default model for execution
- secondaryModel
-
- Fallback model on primary failure
- tags
-
- Capability tags for routing (分析, Debug, implementation, etc.)
- type
-
- Tool type (builtin, cli-wrapper, api-endpoint)
- Universal Prompt Template
- Structure
-
- Every CLI command follows this 6-field template
- ccw cli
- -p
- "PURPOSE: [goal] + [why] + [success criteria] + [scope]
- TASK: • [step 1: specific action] • [step 2: specific action] • [step 3: specific action]
- MODE: [analysis|write|review]
- CONTEXT: @[file patterns] | Memory: [session/tech/module context]
- EXPECTED: [deliverable format] + [quality criteria] + [structure requirements]
- CONSTRAINTS: [domain constraints]"
- --tool
- <
- tool-id
- >
- --mode
- <
- mode
- >
- --rule
- <
- template
- >
- Field Specifications
- PURPOSE (Goal Definition)
- What
-
- Clear objective + motivation + success criteria + scope boundary
- Components
- :
- What: Specific task goal
- Why: Business/technical motivation
- Success: Measurable success criteria
- Scope: Bounded context/files
- Example - Good
- :
- PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module to pass security audit;
- success = all critical/high issues documented with remediation;
- scope = src/auth/** only
- Example - Bad
- :
- PURPOSE: Analyze code
- TASK (Action Steps)
- What
-
- Specific, actionable steps with clear verbs and targets
- Format
-
- Bullet list with concrete actions
- Example - Good
- :
- TASK:
- • Scan for SQL injection in query builders
- • Check XSS in template rendering
- • Verify CSRF token validation
- Example - Bad
- :
- TASK: Review code and find issues
- MODE (Permission Level)
- Options
- :
- analysis
- - Read-only, safe for auto-execution
- write
- - Create/Modify/Delete files, full operations
- review
- - Git-aware code review (codex only)
- Rules
- :
- Always specify explicitly
- Default to
- analysis
- for read-only tasks
- Require explicit
- --mode write
- for file modifications
- Use
- --mode review
- with
- --tool codex
- for git-aware review
- CONTEXT (File Scope + Memory)
- Format
- :
- CONTEXT: @[file patterns] | Memory: [memory context]
- File Patterns
- :
- @*/
- - All files (default)
- @src/*/.ts
- - Specific pattern
- @../shared/*/
- - Parent/sibling (requires
- --includeDirs
- )
- Memory Context
- (when building on previous work):
- Memory: Building on auth refactoring (commit abc123), using JWT for sessions
- Memory: Integration with auth module, shared error patterns from @shared/utils/errors.ts
- EXPECTED (Output Specification)
- What
-
- Output format + quality criteria + structure requirements
- Example - Good
- :
- EXPECTED: Markdown report with:
- severity levels (Critical/High/Medium/Low),
- file:line references,
- remediation code snippets,
- priority ranking
- Example - Bad
- :
- EXPECTED: Report
- CONSTRAINTS (Domain Boundaries)
- What
-
- Scope limits, special requirements, focus areas
- Example - Good
- :
- CONSTRAINTS: Focus on authentication | Ignore test files | No breaking changes
- Example - Bad
- :
- CONSTRAINTS: (missing or too vague)
- CLI Execution Modes
- MODE: analysis
- Permission
-
- Read-only
- Use For
-
- Code review, architecture analysis, pattern discovery, exploration
- Safe
-
- Yes - can auto-execute
- Default
-
- When not specified
- MODE: write
- Permission
-
- Create/Modify/Delete files
- Use For
-
- Feature implementation, bug fixes, documentation, code creation
- Safe
-
- No - requires explicit
- --mode write
- Requirements
-
- Must be explicitly requested by user
- MODE: review
- Permission
-
- Read-only (git-aware review output)
- Use For
-
- Code review of uncommitted changes, branch diffs, specific commits
- Tool Support
- :
- codex
- only (others treat as analysis)
- Constraint
-
- Target flags (
- --uncommitted
- ,
- --base
- ,
- --commit
- ) and prompt are mutually exclusive
- Command Structure
- Basic Command
- ccw cli
- -p
- "
" - --tool
- <
- tool-id
- >
- --mode
- <
- analysis
- |
- write
- |
- review
- >
- Command Options
- Option
- Description
- Example
- --tool
- Tool from config
- --tool gemini
- --mode
- REQUIRED
- analysis/write/review
--mode analysis
--model
Model override --model gemini-2.5-flash --cd Working directory --cd src/auth --includeDirs Additional directories --includeDirs ../shared,../types --rule Auto-load template --rule analysis-review-architecture --resume [id] Resume session --resume or --resume Advanced Directory Configuration Working Directory ( --cd ) When using --cd : @*/ = Files within working directory tree only Cannot reference parent/sibling without --includeDirs Reduces token usage by scoping context Include Directories ( --includeDirs ) Two-step requirement for external files : Add --includeDirs parameter Reference in CONTEXT with @ patterns
Single directory
ccw cli -p "CONTEXT: @/* @../shared//*" \ --tool gemini --mode analysis \ --cd src/auth --includeDirs .. /shared
Multiple directories
ccw cli -p "..." \ --tool gemini --mode analysis \ --cd src/auth --includeDirs .. /shared, .. /types, .. /utils Session Resume When to Use : Multi-round planning (analysis → planning → implementation) Multi-model collaboration (tool A → tool B on same topic) Topic continuity (building on previous findings) Usage : ccw cli -p "Continue analyzing" --tool < tool-id
--mode analysis --resume
Resume last
ccw cli -p "Fix issues found" --tool < tool-id
--mode write --resume < id
Resume specific
ccw cli -p "Merge findings" --tool < tool-id
--mode analysis --resume < id 1
, < id 2
Merge sessions
Available Rule Templates
Template System
Use
--rule
Option 1: Custom focus (reviews uncommitted by default)
ccw cli -p "Focus on security vulnerabilities and error handling" --tool codex --mode review
Option 2: Target flag only (no prompt with target flags)
- ccw cli
- --tool
- codex
- --mode
- review
- --uncommitted
- ccw cli
- --tool
- codex
- --mode
- review
- --base
- main
- ccw cli
- --tool
- codex
- --mode
- review
- --commit
- abc123
- Tool Selection Strategy
- Selection Algorithm
- STEP 0 (REQUIRED)
- Load configuration (memory-first strategy)
Check if configuration exists in conversation memory
If YES → Use in-memory configuration
If NO → Read(file_path="~/.claude/cli-tools.json")
- Then proceed with selection:
- Parse task intent
- → Extract required capabilities
- Load configuration
- → Parse enabled tools with tags from JSON
- Match tags
- → Filter tools supporting required capabilities
- Select tool
- → Choose by priority (explicit > tag-match > default)
- Select model
- → Use primaryModel, fallback to secondaryModel
- Selection Decision Tree
- 0. LOAD CONFIGURATION (memory-first)
- ├─ In memory? → Use it
- └─ Not in memory? → Read ~/.claude/cli-tools.json
- ↓
- 1. Explicit --tool specified?
- YES → Validate tool is enabled in config → Use it
- NO → Proceed to tag-based selection
- ├─ Extract task tags (security, analysis, implementation, etc.)
- │ ├─ Find tools with matching tags
- │ │ ├─ Multiple matches? Use first enabled
- │ │ └─ Single match? Use it
- │ └─ No tag match? Use default tool
- │
- └─ Default: Use first enabled tool in config
- Common Tag Routing
- Note
-
- Match task type to tags defined in
- ~/.claude/cli-tools.json
- Task Type
- Common Tags to Match
- Security audit
- 分析
- ,
- analysis
- ,
- security
- Bug diagnosis
- Debug
- ,
- 分析
- ,
- analysis
- Implementation
- implementation
- , (any enabled tool)
- Testing
- testing
- , (any enabled tool)
- Refactoring
- refactoring
- , (any enabled tool)
- Documentation
- documentation
- , (any enabled tool)
- Selection Logic
-
- Find tools where
- tags
- array contains matching keywords, otherwise use first enabled tool.
- Fallback Chain
- When primary tool fails (based on
- ~/.claude/cli-tools.json
- configuration):
- Check
- secondaryModel
- for same tool (use
- secondaryModel
- from config)
- Try next enabled tool with matching tags (scan config for enabled tools)
- Fall back to default enabled tool (first enabled tool in config)
- Example Fallback
- :
- Tool1: primaryModel fails
- ↓
- Try Tool1: secondaryModel
- ↓ (if fails)
- Try Tool2: primaryModel (next enabled with matching tags)
- ↓ (if fails)
- Try default: first enabled tool
- Permission Framework
- Single-Use Authorization
-
- Each execution requires explicit user instruction. Previous authorization does NOT carry over.
- Mode Hierarchy
- :
- analysis
-
- Read-only, safe for auto-execution
- write
-
- Create/Modify/Delete files - requires explicit
- --mode write
- review
-
- Git-aware code review (codex only) - requires explicit
- --mode review
- Exception
-
- User provides clear instructions like "modify", "create", "implement"
- Auto-Invoke Triggers
- Proactive CLI invocation
- - Auto-invoke
- ccw cli
- when encountering these scenarios:
- Trigger
- Suggested Rule
- When
- Self-repair fails
- analysis-diagnose-bug-root-cause
- After 1+ failed fix attempts
- Ambiguous requirements
- planning-breakdown-task-steps
- Task description lacks clarity
- Architecture decisions
- planning-plan-architecture-design
- Complex feature needs design
- Pattern uncertainty
- analysis-analyze-code-patterns
- Unsure of existing conventions
- Critical code paths
- analysis-assess-security-risks
- Security/performance sensitive
- Execution Principles for Auto-Invoke
- Default mode
- :
- --mode analysis
- (read-only, safe)
- No confirmation needed
-
- Invoke proactively when triggers match
- Wait for results
-
- Complete analysis before next action
- Tool selection
-
- Use context-appropriate tool or fallback chain
- Rule flexibility
- Suggested rules are guidelines, adapt as needed
Best Practices
Core Principles
Configuration-driven
- All tool selection from
cli-tools.json
Tag-based routing
- Match task requirements to tool capabilities
Use tools early and often
- Tools are faster and more thorough than manual analysis
Unified CLI
- Always use
ccw cli -p
for consistent parameter handling
Default to analysis
- Omit
--mode
for read-only, explicitly use
--mode write
for modifications
Use
--rule
for templates
- Auto-loads protocol + template appended to prompt
Write protection
- Require EXPLICIT
--mode write
for file operations
Workflow Principles
Use unified interface
- Always
ccw cli -p
format
Always include template
- Use
--rule
to load templates Be specific - Clear PURPOSE, TASK, EXPECTED fields Include constraints - File patterns, scope in CONSTRAINTS Leverage memory context - When building on previous work Discover patterns first - Use rg/MCP before CLI execution Default to full context - Use @/* unless specific files needed Planning Checklist Purpose defined - Clear goal and intent Mode selected - --mode analysis|write|review Context gathered - File references + memory (default @/* ) Directory navigation - --cd and/or --includeDirs if needed Tool selected - Explicit --tool or tag-based auto-selection Rule template - --rule loads template Constraints - Domain constraints in CONSTRAINTS field Integration with CLAUDE.md Instructions From global CLAUDE.md : Always use run_in_background: false for Task tool agent calls Default: Use Bash run_in_background: true for CLI calls After CLI call: Stop output immediately, wait for hook callback Wait for results: MUST wait for CLI analysis before taking write actions Value every call: Never waste analysis results, aggregate before proposing solutions From cli-tools-usage.md : Strict cli-tools.json configuration adherence Configuration-driven tool selection Template system with --rule auto-loading Permission framework with single-use authorization Auto-invoke triggers for common failure scenarios