claude-code-boost: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code Boost is a TypeScript-based CLI tool that provides intelligent auto-approval hooks for Claude Code. It enhances developer productivity by automatically approving safe development operations while blocking genuinely destructive commands.

Architecture

The project follows a simple CLI architecture:

• Entry Point: src/index.ts - Uses Commander.js for CLI structure
• Main Command: src/commands/auto-approve-tools.ts - Core logic for tool approval decisions
• Hook Integration: Processes Claude Code PreToolUse hooks via stdin/stdout JSON communication
• AI-Powered Decisions: Falls back to Claude API for complex approval decisions
• Type Safety: src/types/hook-schemas.ts - Zod schemas for input/output validation
• Security Model: Two-tier approval system:
  • Fast approval for unambiguously safe tools (Read, LS, Glob, etc.)
  • AI-powered analysis for complex operations using prompts/system-prompt.md

Development Commands

Build and Test

npm run build          # TypeScript compilation to dist/
npm run type-check     # Type checking without compilation
npm run test           # Run test suite with Vitest
npm run test:watch     # Watch mode for tests
npm run test:env       # Run tests with .env.local file

Linting and Formatting

npm run lint           # ESLint checking
npm run lint:fix       # Auto-fix linting issues
npm run prettier       # Format code with Prettier
npm run prettier:check # Check code formatting

Development

npm run dev            # Run CLI with tsx (development mode)
npm run prepublishOnly # Full build + test + lint pipeline

CLI Testing

# Test the CLI locally (requires ANTHROPIC_API_KEY env var or config.json)
echo '{"session_id":"test","transcript_path":"/tmp/test","tool_name":"Read","tool_input":{"file_path":"/test"}}' | ANTHROPIC_API_KEY=your_key npm run dev auto-approve-tools

# Test with API authentication
echo '{"session_id":"test","transcript_path":"/tmp/test","tool_name":"Read","tool_input":{"file_path":"/test"}}' | npm run dev auto-approve-tools

# Install CCB hook to Claude Code settings
npm run build && node dist/index.js install --user        # Install to user settings
npm run build && node dist/index.js install --project     # Install to project settings
npm run build && node dist/index.js install --project-local # Install to project local settings