claudekit

claudekit

Smart guardrails and workflow automation for Claude Code - catch errors in real-time, save checkpoints, and enhance AI coding with expert subagents

Installation

⚠️ Requires: Claude Code Max plan (for optimal token usage) • Node.js 20+

npm install -g claudekit
# or: yarn global add claudekit
# or: pnpm add -g claudekit

⚡ Quick Start

# Initialize in your project
claudekit setup

# In Claude Code, try these commands:
/git:status                      # Groups changes by type & suggests commit strategy
/spec:create "your next feature" # Researches codebase & writes full spec
/code-review                     # 6 specialized agents analyze code in parallel

What It Does

Claudekit acts as your safety net while coding with Claude:

…

Key Features

️ Instant Codebase Navigation

Claude sees your entire project structure automatically - skips most discovery searches.

• Navigate directly to code - Jump straight to files, functions, and classes
• No trial-and-error - Avoid sifting through test files, docs, and irrelevant matches
• Confident code access - Claude knows exactly what exists and where
• See relationships - Claude understands dependencies and architecture instantly
• Automatic setup - Runs invisibly on first prompt, updates as you code

Codebase map guide →

Comprehensive Code Review

• Multi-aspect analysis: 6 parallel agents for architecture, security, performance, testing, quality, and documentation
• Smart targeting: Automatically selects relevant review agents based on file types and scope
• Structured reports: Prioritized issues (Critical/High/Medium) with type icons and actionable solutions
• Quality metrics: Scoring system and issue distribution tracking for measurable improvements

Iterative Spec Implementation

• 6-phase workflow: Implementation → Test Writing → Code Review → Iterative Improvement → Commit → Progress Tracking
• Dynamic agent selection: Real-time detection of available specialized agents with automatic fallbacks
• Quality gates: Each phase includes validation before proceeding to ensure high-quality deliverables
• Atomic commits: Standardized commit messages with comprehensive change documentation

Spec workflow guide →

️ Real-time Error Prevention

• ** Advanced Bash Security Analysis**: Comprehensive protection against sensitive file access via shell commands
  • Intelligent Command Parsing: Analyzes complex bash pipelines, variable assignments, and shell constructs
  • Pattern Detection: Identifies sensitive file access via xargs, find, pipes, and command substitution
  • Path Extraction: Safely processes globs, variables, and @file references in curl/httpie uploads
  • Security Heuristics: Detects risky patterns like find -name '*.env' | xargs cat before execution
• ** Enhanced Sensitive File Protection**: Comprehensive security with 195+ patterns across 12 categories including cloud credentials, cryptocurrencies, databases, tokens, and production data
• Multi-category Protection: Environment files, SSH keys, cloud provider credentials (AWS/Azure/GCP), package manager auth, crypto wallets, production databases
• TypeScript Guard: Blocks any types and type errors as Claude edits
• Linting: Catches style issues immediately
• Anti-patterns: Prevents code replacement with comments
• Test Runner: Runs relevant tests on file changes
• Multi-tool ignore file support: Respects .agentignore, .aiignore, .aiexclude, .geminiignore, .codeiumignore, .cursorignore

Git Checkpoint System

• Auto-save: Creates checkpoints when Claude stops
• Easy restore: /checkpoint:restore to undo changes
• Checkpoint management: List, restore, or clean up checkpoints

Checkpoint guide →

AI Subagents

• Research Expert: research-expert for comprehensive parallel research with 90% time reduction, automatic source analysis, and structured reporting
• Code Search: code-search for fast, parallel codebase searches with 3-10x speed improvements
• Triage Expert: triage-expert for initial problem diagnosis and routing to specialists
• Domain experts: TypeScript, React, database, testing, infrastructure, documentation specialists
• Code review: Dedicated code-review-expert agent with 6 focused analysis aspects
• Framework specialists: Next.js, Nest.js, AI SDK, and build tool experts
• Performance optimization: Intelligent hook management with disableHooks configuration to skip unnecessary validations during specialized operations
• Mandatory delegation: All technical issues MUST be handled by specialized subagents
• Proactive help: Run /agents-md:init to update AGENTS.md/CLAUDE.md for automatic subagent delegation

Hook Performance Profiling

• Performance monitoring: Analyze hook execution time and output size with claudekit-hooks profile
• Batch analysis: Automatically profiles all configured hooks from .claude/settings.json
• Statistical analysis: Support for multiple iterations with averaging for accurate measurements
• Smart warnings: Color-coded alerts for slow hooks (>5s) and output size limits
• Claude Code integration: Specialized limits for UserPromptSubmit hooks that inject context
• Token estimation: Calculate estimated token usage for hook outputs

Hook profiling guide →

Enhanced AI Reasoning

• Automatic enhancement: The thinking-level hook invisibly enhances Claude's reasoning without manual prompt engineering
• 4 configurable levels: From disabled (0) to maximum reasoning (3) with smart defaults
• Invisible operation: Keywords are injected silently without user awareness
• Lightweight: # Execute a specific hook manually claudekit-hooks profile # Profile all configured hooks performance claudekit-hooks profile --iterations 5 # Profile specific hook with averaging

Session-based hook control (within Claude Code sessions)

claudekit-hooks disable # Disable hook for current session claudekit-hooks enable # Re-enable hook for current session
claudekit-hooks status # Show hook status (enabled/disabled)

### Using Prompts with External LLMs

The `show` command extracts agent and command prompts for use with Claude Code's non-interactive mode and other AI coding tools:

```bash
# Extract agent prompt for use with Claude Code CLI
EXPERT=$(claudekit show agent typescript-expert)
cat src/app.ts | claude -p --append-system-prompt "$EXPERT" "Review this code"

# Get structured metadata for integration with tools
claudekit show agent typescript-expert --format json | jq '.description'

# Works with any AI coding CLI tool
claudekit show agent react-expert | amp -x "Fix React hooks violations"

…

bash
# See all available hooks with descriptions
claudekit-hooks list

# Profile hook performance and output size
claudekit-hooks profile                   # Profile all hooks
claudekit-hooks profile typecheck-changed  # Profile specific hook
claudekit-hooks profile --iterations 5    # Multiple runs for averages

# Session-based hook control (requires active Claude Code session)
claudekit-hooks disable typecheck-changed  # Disable specific hook for current session
claudekit-hooks enable typecheck          # Re-enable hook (supports partial matching)
claudekit-hooks status                     # Show status of all hooks
claudekit-hooks status lint                # Show status of specific hook

…

bash
# List all available agents with token counts
claudekit list agents

# Install specific agents
claudekit setup --agents typescript-expert,react-expert

Once installed, agents work automatically or can be invoked directly:

"Use the oracle agent to debug this issue"
"Have the typescript-expert review this type definition"

View all agents →

Security

Protecting Sensitive Files

The file-guard hook automatically protects sensitive files from AI access. Quick setup:

# New projects: Install claudekit with file-guard protection
npm install -g claudekit && claudekit setup --yes --force --hooks file-guard

# Existing projects: Add file-guard to current setup
claudekit setup --yes --force --hooks file-guard

Or manually create a .agentignore file:

# .agentignore
.env
.env.*
*.key
*.pem
.aws/credentials
.ssh/*

# Allow example files
!.env.example

…

json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read|Edit|MultiEdit|Write",
      "hooks": [{"type": "command", "command": "claudekit-hooks run file-guard"}]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{"type": "command", "command": "claudekit-hooks run typecheck-changed"}]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "claudekit-hooks run create-checkpoint"}]
    }],
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "claudekit-hooks run create-checkpoint"}]
    }],
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "claudekit-hooks run codebase-map"}]
    }]
  }
}

.claudekit/config.json - Hook configuration

{
  "hooks": {
    "typecheck-changed": {
      "command": "npm run typecheck"
    },
    "thinking-level": {
      "level": 2
    },
    "codebase-map": {
      "include": ["src/**", "lib/**"],
      "exclude": ["**/*.test.ts", "**/*.spec.ts"],
      "format": "dsl"
    }
  }
}

Configuration guide →

Getting Help

• Documentation: Full docs
• Issues: GitHub Issues
• Quick test: claudekit doctor to check setup

Common Issues

Hooks not triggering?

claudekit doctor                # Check configuration
npm list -g claudekit           # Verify installation

Tests timing out? Use the ultra-fast test configuration for hook execution:

{
  "hooks": {
    "test-project": {
      "command": "npm run test:fast",
      "timeout": 30000
    }
  }
}

Or configure a custom faster test command:

{
  "hooks": {
    "test-project": {
      "command": "npm run test:unit",
      "timeout": 50000
    }
  }
}

Codebase map not generating? Install the codebase-map CLI tool:

npm install -g codebase-map
# Check installation:
codebase-map --version

Full troubleshooting →

MCP Integration

Some commands support optional MCP server integration:

Context7 (for documentation access)

# Install globally
npm install -g @upstash/context7-mcp

# Add to Claude Code
claude mcp add context7 context7-mcp

Enables /spec:create to fetch up-to-date library documentation.

Development

# Clone and install
git clone https://github.com/claudekit/claudekit.git
cd claudekit
npm install

# Build
npm run build

# Test
npm test

# Validate production build
npm run validate:build         # Check dependencies and build artifacts
npm run validate:install       # Test clean installation

# Create symlinks for development
npm run symlinks

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT © claudekit contributors