Smart hooks for Claude Code that reduce friction and keep quality high.

• Auto-approve safe dev operations (less clicking, more coding)
• Nudge/run tests before ending sessions when changes warrant it
• Optional desktop notifications for long-running tasks

npm install -g claude-code-boost
ccb install

See what gets auto-approved and blocked in the sections below.

Prerequisites: Node.js 20+ and Claude Code installed

# Step 1: Install Claude Code Boost globally
npm install -g claude-code-boost

# Step 2: Run the install command to set up the hook
ccb install

The ccb install command guides you through:

1. Choose installation location (user, project, or project-local settings)
2. Choose authentication method (API proxy or direct API key)
3. Configure Claude Code settings automatically
4. Verify the setup works

Reduces manual approval overhead by automatically approving common safe operations:

• File operations (reading, writing, basic file management)
• Standard build/test commands (npm test, npm build, git commit)
• Local development requests (curl localhost:3000)
• Package management (npm install, dependency updates)
• Basic Docker operations

Always blocks destructive system commands (rm -rf /, disk formatting, etc.)

Analyzes conversation transcripts to detect when tests should be run before ending a session:

• Parses Claude Code conversation history
• Uses LLM analysis to determine if code changes warrant testing
• Can block session termination until tests are executed

Simple desktop notifications for Claude Code events:

• Cross-platform support (macOS, Windows, Linux)
• Useful for long-running operations or important alerts

Utility for processing Claude Code conversation logs:

• Converts JSONL transcript format to structured XML
• Extracts user messages, assistant responses, and commands
• Useful for analysis or integration with other tools

Claude Code Boost uses Claude Code's hook system to intercept tool calls before execution:

Claude Code Tool Request → CCB Hook → Decision → Execute/Block

1. Fast approval for obviously safe operations (Read, LS, Glob)
2. LLM analysis for complex operations using system prompts
3. Caching to avoid redundant API calls for identical requests
4. Always block genuinely destructive commands

• beyondthehype.dev API proxy (simplest setup)
• OpenAI API (for OpenAI or compatible endpoints)
• Anthropic API (direct Claude access)

# Interactive installation with prompts
ccb install --user

# Non-interactive with API key  
ccb install --user --api-key sk-your-api-key-here

# Use project-level settings
ccb install --project-local

CCB uses a configuration file located at ~/.ccb/config.json (or $CCB_CONFIG_DIR/config.json):

{
  "log": true,        // Enable/disable approval logging
  "cache": true,      // Enable/disable approval caching (default: true)  
  "apiKey": "sk-..."  // Anthropic API key (optional)
}

Configuration Options:

• log (boolean, default: true): Controls whether approval decisions are logged to ~/.ccb/approval.jsonl
• cache (boolean, default: true): Controls intelligent caching of approval decisions to avoid redundant AI calls
• apiKey (string, optional): Anthropic API key for direct API access (overrides ANTHROPIC_API_KEY environment variable)

Caching Behavior:

• ✅ Enabled by default for optimal performance
• 🏠 Working directory scoped for safety across different projects
• 🎯 Caches only definitive decisions (approve/block, not "unsure")
• 🚀 Instant responses for repeated operations
• 🧹 Easy management with ccb debug clear-approval-cache

# Disable caching if needed
echo '{"log": true, "cache": false}' > ~/.ccb/config.json

# Clear approval cache
ccb debug clear-approval-cache

• File operations: Reading, writing, editing files
• Development tools: npm test, npm build, git commit
• Localhost requests: curl http://localhost:3000
• Docker operations: docker build, docker run
• Package management: npm install, yarn add

• System destruction: rm -rf /, rm -rf /usr
• Disk operations: mkfs, destructive fdisk
• Malicious activity: DoS attacks, credential theft

# Test safe operation approval
echo '{"session_id":"test","transcript_path":"/tmp/test","tool_name":"Read","tool_input":{"file_path":"/etc/hosts"}}' | ccb auto-approve-tools
# Expected: {"decision":"approve","reason":"Read is a safe read-only operation"}

# Test dangerous operation blocking
echo '{"session_id":"test","transcript_path":"/tmp/test","tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | ccb auto-approve-tools
# Expected: {"decision":"block","reason":"..."}

# Test notification system
echo '{"session_id":"test","transcript_path":"/tmp/test","cwd":"/tmp","hook_event_name":"Notification","message":"Test notification from CCB"}' | ccb notification

# Test Stop hook (requires transcript file)
echo '{"session_id":"test","transcript_path":"/path/to/transcript.jsonl","cwd":"/tmp","stop_hook_active":false}' | ccb enforce-tests

# Clear approval cache
ccb debug clear-approval-cache

# View current config
cat ~/.ccb/config.json

# View approval logs  
tail -f ~/.ccb/approval.jsonl

# View cached decisions
cat ~/.ccb/approval_cache.json

Claude Code Boost aims to make Claude Code more practical for daily development work by reducing friction in common workflows.

• 🛡️ Auto-approval for safe operations (reduces manual clicking)
• 🧪 Test enforcement through conversation analysis
• 🔔 Basic desktop notifications
• 📊 Transcript parsing utilities

• Better caching strategies to reduce API costs
• More sophisticated test detection patterns
• Additional hook types based on user feedback
• Performance optimizations

This is an early-stage project that solves real workflow friction. Contributions and feedback are welcome as we figure out what developers actually need from Claude Code automation.

• Issues: Report bugs or request features
• Discussions: Share usage patterns and suggestions
• Documentation: Development setup in CLAUDE.md
• Contributing: See CLAUDE.md for local development instructions

MIT License - see LICENSE file for details.

npm install -g claude-code-boost && ccb install