CLI Tools - Unified Execution Framework

~/.claude/cli-tools.json

Initialization (Required First Step)

1. Check if configuration exists in memory:
   • If configuration is already in conversation memory → Use it directly
   • If NOT in memory → Read the configuration file:
     bash

     Read(file_path="~/.claude/cli-tools.json")

2. 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)
3. Use configuration throughout the selection process

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 "<PROMPT>" --tool <tool> --mode <mode> --rule <rule>
│
└─ STEP 7: Handle Results
   ├─ On success → Deliver output to user
   └─ On failure → Check secondaryModel or fallback tool

Configuration Reference

Configuration File Location

~/.claude/cli-tools.json

Reading Configuration

• 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

Configuration Structure

tools

enabled

true

false

primaryModel

"gemini-2.5-pro"

secondaryModel

"gemini-2.5-flash"

tags

["分析", "Debug"]

type

"builtin"

"cli-wrapper"

"api-endpoint"

Expected Tools (Reference Only)

gemini

qwen

codex

claude

opencode

~/.claude/cli-tools.json

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

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: Specific task goal
• Why: Business/technical motivation
• Success: Measurable success criteria
• Scope: Bounded context/files

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

PURPOSE: Analyze code

TASK (Action Steps)

TASK:
• Scan for SQL injection in query builders
• Check XSS in template rendering
• Verify CSRF token validation

TASK: Review code and find issues

MODE (Permission Level)

• analysis

  - Read-only, safe for auto-execution

• write

  - Create/Modify/Delete files, full operations

• review

  - Git-aware code review (codex only)

• 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)

CONTEXT: @[file patterns] | Memory: [memory context]

• @**/*

  - All files (default)

• @src/**/*.ts

  - Specific pattern

• @../shared/**/*

  - Parent/sibling (requires

  --includeDirs

  )

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)

EXPECTED: Markdown report with:
severity levels (Critical/High/Medium/Low),
file:line references,
remediation code snippets,
priority ranking

EXPECTED: Report

CONSTRAINTS (Domain Boundaries)

CONSTRAINTS: Focus on authentication | Ignore test files | No breaking changes

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 "<PROMPT>" --tool <tool-id> --mode <analysis|write|review>

Command Options

--tool <tool>

--tool gemini

--mode <mode>

--mode analysis

--model <model>

--model gemini-2.5-flash

--cd <path>

--cd src/auth

--includeDirs <dirs>

--includeDirs ../shared,../types

--rule <template>

--rule analysis-review-architecture

--resume [id]

--resume

--resume <id>

Advanced Directory Configuration

Working Directory (

--cd

)

--cd

• @**/*

  = Files within working directory tree only
• Cannot reference parent/sibling without

  --includeDirs

• Reduces token usage by scoping context

Include Directories (

--includeDirs

)

1. Add

   --includeDirs

   parameter
2. 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

• Multi-round planning (analysis → planning → implementation)
• Multi-model collaboration (tool A → tool B on same topic)
• Topic continuity (building on previous findings)

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 <id1>,<id2>      # Merge sessions

Available Rule Templates

Template System

--rule <template-name>

Universal Templates

• universal-rigorous-style

  - Precise tasks (default)

• universal-creative-style

  - Exploratory tasks

Analysis Templates

• analysis-trace-code-execution

  - Execution tracing

• analysis-diagnose-bug-root-cause

  - Bug diagnosis

• analysis-analyze-code-patterns

  - Code patterns

• analysis-analyze-technical-document

  - Document analysis

• analysis-review-architecture

  - Architecture review

• analysis-review-code-quality

  - Code review

• analysis-analyze-performance

  - Performance analysis

• analysis-assess-security-risks

  - Security assessment

Planning Templates

• planning-plan-architecture-design

  - Architecture design

• planning-breakdown-task-steps

  - Task breakdown

• planning-design-component-spec

  - Component design

• planning-plan-migration-strategy

  - Migration strategy

Development Templates

• development-implement-feature

  - Feature implementation

• development-refactor-codebase

  - Code refactoring

• development-generate-tests

  - Test generation

• development-implement-component-ui

  - UI component

• development-debug-runtime-issues

  - Runtime debugging

Task-Type Specific Examples

Example 1: Security Analysis (Read-Only)

ccw cli -p "PURPOSE: Identify OWASP Top 10 vulnerabilities in authentication module to pass security audit; success = all critical/high issues documented with remediation
TASK: • Scan for injection flaws (SQL, command, LDAP) • Check authentication bypass vectors • Evaluate session management • Assess sensitive data exposure
MODE: analysis
CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt for passwords, JWT for sessions
EXPECTED: Security report with: severity matrix, file:line references, CVE mappings where applicable, remediation code snippets prioritized by risk
CONSTRAINTS: Focus on authentication | Ignore test files
" --tool gemini --mode analysis --rule analysis-assess-security-risks --cd src/auth

Example 2: Feature Implementation (Write Mode)

ccw cli -p "PURPOSE: Implement rate limiting for API endpoints to prevent abuse; must be configurable per-endpoint; backward compatible with existing clients
TASK: • Create rate limiter middleware with sliding window • Implement per-route configuration • Add Redis backend for distributed state • Include bypass for internal services
MODE: write
CONTEXT: @src/middleware/**/* @src/config/**/* | Memory: Using Express.js, Redis already configured, existing middleware pattern in auth.ts
EXPECTED: Production-ready code with: TypeScript types, unit tests, integration test, configuration example, migration guide
CONSTRAINTS: Follow existing middleware patterns | No breaking changes
" --tool gemini --mode write --rule development-implement-feature

Example 3: Bug Root Cause Analysis

ccw cli -p "PURPOSE: Fix memory leak in WebSocket connection handler causing server OOM after 24h; root cause must be identified before any fix
TASK: • Trace connection lifecycle from open to close • Identify event listener accumulation • Check cleanup on disconnect • Verify garbage collection eligibility
MODE: analysis
CONTEXT: @src/websocket/**/* @src/services/connection-manager.ts | Memory: Using ws library, ~5000 concurrent connections in production
EXPECTED: Root cause analysis with: memory profile, leak source (file:line), fix recommendation with code, verification steps
CONSTRAINTS: Focus on resource cleanup
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause --cd src

Example 4: Code Review (Codex Review Mode)

# 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

# Check if configuration exists in conversation memory
# If YES → Use in-memory configuration
# If NO → Read(file_path="~/.claude/cli-tools.json")

1. Parse task intent → Extract required capabilities
2. Load configuration → Parse enabled tools with tags from JSON
3. Match tags → Filter tools supporting required capabilities
4. Select tool → Choose by priority (explicit > tag-match > default)
5. 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

~/.claude/cli-tools.json

分析

analysis

security

Debug

分析

analysis

implementation

testing

refactoring

documentation

tags

Fallback Chain

~/.claude/cli-tools.json

1. Check

   secondaryModel

   for same tool (use

   secondaryModel

   from config)
2. Try next enabled tool with matching tags (scan config for enabled tools)
3. Fall back to default enabled tool (first enabled tool in config)

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

• 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

ccw cli

analysis-diagnose-bug-root-cause

planning-breakdown-task-steps

planning-plan-architecture-design

analysis-analyze-code-patterns

analysis-assess-security-risks

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 <template-name>

  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 <template-name>

  loads template
• Constraints - Domain constraints in CONSTRAINTS field

Integration with CLAUDE.md Instructions

• 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

• 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