6. Slash Commands

6.1 Slash Commands

Slash commands are shortcuts for common workflows.

Built-in Commands

Command	Action
/help	Show all commands
/clear	Clear conversation
/compact	Summarize context
/status	Show session info
/plan	Enter Plan Mode
/rewind	Undo changes
/voice	Toggle voice input (hold Space to speak, release to send)
/simplify	Review changed code and fix over-engineering
/batch	Large-scale changes via parallel worktree agents
/insights	Generate usage analytics report
/exit	Exit Claude Code

The /insights Command

/insights analyzes your Claude Code usage history to generate a comprehensive report identifying patterns, friction points, and optimization opportunities.

What It Analyzes

The command processes your session data to detect:

• Project areas: Automatically clusters your work into thematic areas (e.g., “Frontend Development”, “CLI Tooling”, “Documentation”) with session counts
• Interaction style: Identifies your workflow patterns (plan-driven, exploratory, iterative, supervisory)
• Success patterns: Highlights what’s working well in your usage (multi-file coordination, debugging approaches, tool selection)
• Friction categories: Pinpoints recurring issues (buggy code, wrong directories, context loss, misunderstood requests)
• Tool usage: Tracks which tools you use most (Bash, Read, Edit, Grep, etc.) and identifies optimization opportunities
• Multi-clauding behavior: Detects parallel session patterns (running multiple Claude instances simultaneously)
• Temporal patterns: Identifies your most productive time windows and response time distribution

What It Produces

Running /insights generates an interactive HTML report at ~/.claude/usage-data/report.html containing:

At a Glance Summary:

• What’s working: 2-3 sentences on successful patterns
• What’s hindering: 2-3 sentences on main friction points
• Quick wins: 1-2 actionable suggestions (setup time < 5 minutes)
• Ambitious workflows: 1-2 advanced patterns for future exploration

Detailed Sections:

1. What You Work On: 3-5 auto-detected project areas with descriptions
2. How You Use Claude Code: Narrative analysis (2-3 paragraphs) of your interaction style + key pattern summary
3. Impressive Things You Did: 3 “big wins” — sophisticated workflows the system detected (e.g., multi-agent reviews, custom automation layers)
4. Where Things Go Wrong: 3 friction categories with examples and mitigation strategies
5. Existing CC Features to Try:
   • 6+ CLAUDE.md additions (pre-formatted, ready to copy)
   • 3 features with setup code (Custom Skills, Hooks, Task Agents)
6. New Ways to Use Claude Code: 3 usage patterns with copyable prompts
7. On the Horizon: 3 ambitious workflows with detailed implementation prompts (300+ tokens each)
8. Fun Ending: An anecdote from your sessions (e.g., a memorable user intervention or pattern)

Interactive Elements:

• Copy buttons for all code snippets and prompts
• Checkboxes for CLAUDE.md additions (bulk copy)
• Charts and visualizations (tool usage, friction types, outcomes, time-of-day distribution)
• Navigation TOC with anchor links
• Responsive design (works on mobile)

How to Use It

Basic usage:

/insights

The command runs silently (no progress output) and takes ~10-30 seconds depending on session count. You’ll see:

1281 sessions · 10,442 messages · 3445h · 1160 commits
2025-12-15 to 2026-02-06

## At a Glance
[4 summary sections...]

Report URL: file:///Users/you/.claude/usage-data/report.html

Open the report:

• CLI: open ~/.claude/usage-data/report.html (macOS) or xdg-open ~/.claude/usage-data/report.html (Linux)
• The report is self-contained HTML (no external dependencies)

When to run it:

• After major projects: Identify what worked and what to improve for next time
• Monthly: Track evolution of your workflow patterns
• When feeling stuck: Get data-driven suggestions for friction points
• Before optimizing CLAUDE.md: See which patterns to codify
• When context feels broken: Check if detected patterns explain frustration

Typical Insights Generated

The report may identify patterns like:

Friction categories:

• “Buggy Code Requiring Multiple Fix Rounds” (22 instances) → Suggests build-check-fix loops after each edit
• “Wrong Directory Before Starting Work” (12 instances) → Recommends explicit working directory confirmation in CLAUDE.md
• “Insufficient Real-World Testing” → Proposes manual testing protocols beyond automated checks
• “Context Loss” → Flags sessions where conversation became disconnected from original goal

Success patterns:

• “Plan-Driven Execution at Scale” → Detects users who provide numbered plans and achieve 80%+ completion rates
• “Multi-Agent Review and Challenge Loops” → Identifies sophisticated users who spawn sub-agents for adversarial review
• “Custom Slash Commands for Recurring Workflows” → Highlights automation layer patterns

CLAUDE.md suggestions (example):

## Project Directories
Always confirm the correct working directory before starting work:
- Frontend: /path/to/web-app
- Backend: /path/to/api
- Docs: /path/to/documentation
Never assume which project to work in — ask if ambiguous.

Feature recommendations (example):

• “Your #1 friction is buggy code (22 occurrences). A pre-commit hook running build checks would catch these before they compound.”
• “You run 73% of messages in parallel sessions (multi-clauding). Consider a session coordination protocol in CLAUDE.md.”

Horizon workflows (example):

Self-Healing Builds With Test-Driven Agents

Implement the following plan step by step. After EVERY file edit,
run the full build command. If the build fails, immediately diagnose
the error, fix it, and rebuild before moving to the next step.
Never proceed with a broken build.

[300-token detailed prompt follows...]

Technical Details

• Analysis engine: Uses Claude Haiku (fast, cost-effective)
• Session limit: Analyzes up to 50 recent sessions per run
• Token budget: Max 8192 tokens per analysis pass
• Data location: ~/.claude/usage-data/ (sessions stored as JSONL)
• Privacy: All analysis runs locally; no data sent to external services beyond standard Claude Code API usage

How /insights Works (Architecture Overview)

The analysis pipeline processes session data through 7 stages:

1. Session Filtering: Loads from ~/.claude/projects/, excludes agent sub-sessions, sessions with <2 user messages, or <1 minute duration
2. Transcript Summarization: Chunks sessions exceeding 30,000 characters into 25,000-character segments
3. Facet Extraction: Uses Claude Haiku to classify sessions into structured categories
4. Aggregated Analysis: Detects cross-session patterns and recurring workflows
5. Executive Summary: Generates “At a Glance” synthesis across four dimensions
6. Report Generation: Renders interactive HTML with visualizations and narrative sections
7. Facet Caching: Saves classifications to ~/.claude/usage-data/facets/<session-id>.json for fast subsequent runs

Facets Classification System:

The system categorizes sessions using these dimensions:

Goals (13 types): Debug/Investigate, Implement Feature, Fix Bug, Write Script/Tool, Refactor Code, Configure System, Create PR/Commit, Analyze Data, Understand Codebase, Write Tests, Write Docs, Deploy/Infra, Cache Warmup

Friction Types (12 categories): Misunderstood requests, Wrong approach, Buggy code, User rejected actions, Claude blocked, Early user stoppage, Wrong file locations, Over-engineering, Slowness/verbosity, Tool failures, Unclear requests, External issues

Satisfaction Levels (6): Frustrated → Dissatisfied → Likely Satisfied → Satisfied → Happy → Unsure

Outcomes (4 states): Not Achieved → Partially Achieved → Mostly Achieved → Fully Achieved

Success Categories (7): Fast accurate search, Correct code edits, Good explanations, Proactive help, Multi-file changes, Good debugging, None

Session Types (5): Single task, Multi-task, Iterative refinement, Exploration, Quick question

Understanding these categories helps interpret your report:

• High “Buggy code” friction → Consider implementing pre-commit hooks (see Hooks feature)
• Low satisfaction on “Implement Feature” goals → Improve planning phase specificity
• “Early user stoppage” pattern → May indicate requests lack sufficient context

Performance optimization: The caching system ensures subsequent runs only analyze new sessions (not previously classified ones), making regular monthly runs fast even with large session histories.

Source: Architecture details from Zolkos Technical Deep Dive (2026-02-04)

Limitations

• Requires history: Needs at least ~10 sessions for meaningful patterns
• Recency bias: Focuses on last 50 sessions (older patterns not detected)
• Model-estimated satisfaction: Satisfaction scores are inferred, not explicit user ratings
• No cross-project aggregation: Each project analyzed independently (no global patterns across multiple repos)

Integration with Other Tools

Feed insights into CLAUDE.md:

# 1. Generate report
/insights

# 2. Open report in browser
open ~/.claude/usage-data/report.html

# 3. Copy CLAUDE.md additions (use checkboxes + "Copy All Checked")
# 4. Paste into Claude Code:
"Add these CLAUDE.md sections: [paste copied text]"

Track evolution over time:

# Save timestamped reports
cp ~/.claude/usage-data/report.html ~/insights-reports/$(date +%Y-%m-%d).html

# Compare monthly
diff ~/insights-reports/2026-01-01.html ~/insights-reports/2026-02-01.html

Combine with other analytics:

• Use with ccboard skill for deeper dive into session economics
• Cross-reference with git history: git log --since="2025-12-15" --until="2026-02-06" --oneline | wc -l
• Compare detected friction with actual bug reports

Example Workflow

Monthly optimization routine:

# 1. Generate current insights
/insights

# 2. Review "What's hindering you" section
# Note: Common friction → buggy code (48% of events)

# 3. Implement quick win (PostToolUse hook for build checks)
cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run build 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}
EOF

# 4. Update CLAUDE.md with detected patterns
# (Copy from "Suggested CLAUDE.md Additions" section)

# 5. Re-run next month to measure improvement

Comparison with Other Analytics

Tool	Scope	Output	Use Case
/insights	Session behavior, friction, patterns	Interactive HTML report	Workflow optimization, self-improvement
/status	Current session only	Text summary (context, costs, tools)	Real-time monitoring
ccboard	Economics, cost analysis, project breakdown	TUI/Web dashboard	Budget tracking, cost optimization
Git history	Code changes only	Commit log	Delivery metrics, PR velocity

Tip: Run /insights monthly, /status per session, and ccboard weekly for comprehensive visibility.

The /simplify Command

Added in v2.1.63, /simplify is a bundled slash command that reviews your recently changed code for over-engineering and redundant abstractions, then fixes the problems it finds.

When to Use It

Run it after finishing a feature, before opening a pull request:

# Review everything changed since last commit
/simplify

# Focus on a specific concern
/simplify focus on error handling
/simplify check for unnecessary dependencies
/simplify look at the database query patterns

What It Does

/simplify analyzes changed code for:

• Reuse — duplicated logic that could be extracted
• Quality — patterns that reduce readability or maintainability
• Efficiency — algorithmic and structural improvements

It operates at the architecture and structure level, not at the formatter or linter level. /simplify complements tools like ESLint or Prettier rather than replacing them.

Positioning

Tool	Level	Fixes
Prettier	Formatting	Style, whitespace
ESLint	Syntax rules	Simple patterns, unused vars
/simplify	Architecture	Over-abstraction, duplication, design

Note: /simplify is a bundled slash command (ships with Claude Code), not a custom skill you need to create. Available from v2.1.63+.

The /batch Command

Added in v2.1.63, /batch orchestrates large-scale codebase changes by distributing work across 5–30 parallel agents in isolated git worktrees, each opening its own pull request.

How It Works

1. Research & plan — analyzes the codebase and breaks the change into independent units
2. Parallel execution — spawns 5–30 isolated git worktree agents simultaneously
3. PR per agent — each agent completes its portion and opens a pull request

Usage

/batch migrate from react to vue
/batch replace all uses of lodash with native equivalents
/batch add type annotations to all JavaScript files

When to Use It

/batch is the native equivalent of the parallel worktrees multi-agent pattern (see §15). Use it for large, repetitive, file-level changes that can be split into independent units: migrations, refactors, bulk type annotations, dependency replacements.

Note: Both /simplify and /batch are bundled slash commands that ship with Claude Code v2.1.63+. No configuration required.

Custom Commands

You can create your own commands in .claude/commands/:

/tech:commit    → .claude/commands/tech/commit.md
/tech:pr        → .claude/commands/tech/pr.md
/product:scope  → .claude/commands/product/scope.md

6.2 Creating Custom Commands

Commands are markdown files that define a process.

Command File Location

.claude/commands/
├── tech/           # Development workflows
│   ├── commit.md
│   └── pr.md
├── product/        # Product workflows
│   └── problem-framer.md
└── support/        # Support workflows
    └── ticket-analyzer.md

Command Naming

File	Invocation
commit.md in tech/	/tech:commit
pr.md in tech/	/tech:pr
problem-framer.md in product/	/product:problem-framer

Variable Interpolation

Commands can accept arguments:

# My Command

You received the following arguments: $ARGUMENTS[0] $ARGUMENTS[1] $ARGUMENTS[2]
(Or use shorthand: $0 $1 $2)

Process them accordingly.

Usage:

/tech:deploy production

$ARGUMENTS[0] (or $0) becomes production.

⚠️ Breaking Change (v2.1.19): The argument syntax changed from dot notation ($ARGUMENTS.0) to bracket syntax ($ARGUMENTS[0]). If you have existing custom commands using the old syntax, update them:

# Old (< v2.1.19):
$ARGUMENTS.0 $ARGUMENTS.1

# New (v2.1.19+):
$ARGUMENTS[0] $ARGUMENTS[1]
# Or use shorthand:
$0 $1

6.3 Command Template

# Command Name

## Purpose

[Brief description of what this command does]

## Process

Follow these steps:

1. **Step 1 Name**
   [Detailed instructions]

2. **Step 2 Name**
   [Detailed instructions]

3. **Step 3 Name**
   [Detailed instructions]

## Arguments

If arguments provided:
- First argument: $ARGUMENTS[0] (or $0)
- Second argument: $ARGUMENTS[1] (or $1)
- Handle accordingly: [Instructions]
If no arguments: [Default behavior]

## Output Format

[Expected output structure]

## Examples

### Example 1
Input: `/command arg1`
Output: [Expected result]

## Error Handling

If [error condition]:
- [Recovery action]

6.4 Command Examples

Example 1: Commit Command

# Commit Current Changes

## Purpose

Create a well-formatted git commit following Conventional Commits.

## Process

1. **Check Status**
   Run `git status` to see all changes.

2. **Analyze Changes**
   Run `git diff` to understand what changed.

3. **Review History**
   Run `git log -5 --oneline` to see recent commit style.

4. **Draft Message**
   Create commit message following:
   - `feat`: New feature
   - `fix`: Bug fix
   - `refactor`: Code restructuring
   - `docs`: Documentation
   - `test`: Test changes
   - `chore`: Maintenance

5. **Stage and Commit**
   ```bash
   git add [relevant files]
   git commit -m "[type](scope): description"

6. Verify Run git status to confirm commit succeeded.

Arguments

If $ARGUMENTS[0] provided:

• Use as commit message hint: “$ARGUMENTS[0]” (or “$0”)

Output Format

Commit: [hash] [message] Files: [number] changed

Example 2: PR Command

# Create Pull Request

## Purpose

Create a well-documented pull request on GitHub.

## Process

1. **Check Branch State**
   - `git status` - Verify clean working directory
   - `git branch` - Confirm on feature branch
   - `git log main..HEAD` - Review all commits

2. **Analyze Changes**
   - `git diff main...HEAD` - See all changes vs main
   - Understand the full scope of the PR

3. **Push if Needed**
   If branch not pushed:
   ```bash
   git push -u origin [branch-name]

4. Create PR

gh pr create --title "[title]" --body "[body]"

PR Body Template

## Summary
[1-3 bullet points describing changes]

## Changes
- [Specific change 1]
- [Specific change 2]

## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] No regressions

## Screenshots
[If UI changes]

Arguments

If $ARGUMENTS[0] provided:

• Use as PR title hint: “$ARGUMENTS[0]” (or “$0”)

Error Handling

If not on feature branch:

• WARN: “Create a feature branch first”

If working directory dirty:

• ASK: “Commit changes first?”

Example 3: Problem Framer Command

# Problem Framer

## Purpose

Challenge and refine problem definitions before solution design.

## Process

1. **Capture Initial Problem**
   Record the problem as stated by user.

2. **5 Whys Analysis**
   Ask "Why?" 5 times to find root cause:
   - Why 1: [First answer]
   - Why 2: [Deeper answer]
   - Why 3: [Even deeper]
   - Why 4: [Getting to root]
   - Why 5: [Root cause]

3. **Stakeholder Analysis**
   - Who is affected?
   - Who has decision power?
   - Who benefits from solution?

4. **Constraint Identification**
   - Technical constraints
   - Business constraints
   - Time constraints
   - Resource constraints

5. **Success Criteria**
   Define measurable outcomes:
   - [Metric 1]: [Target]
   - [Metric 2]: [Target]

6. **Reframe Problem**
   Write refined problem statement:
   "How might we [action] for [user] so that [outcome]?"

## Output Format

### Problem Analysis Report

**Original Problem**: [As stated]

**Root Cause**: [From 5 Whys]

**Refined Problem Statement**:
"How might we [X] for [Y] so that [Z]?"

**Success Criteria**:
1. [Measurable outcome 1]
2. [Measurable outcome 2]

**Constraints**:
- [Constraint 1]
- [Constraint 2]

---

7. Hooks

Quick jump: The Event System · Creating Hooks · Hook Templates · Security Hooks · Hook Examples

---