ClaudeFast Permission Hook

Intelligent auto-approval for Claude Code that reduces friction and maintains security.

• Auto-approve safe dev operations (less clicking, more coding)
• Block destructive commands automatically (no LLM needed)
• Uses the new PermissionRequest hook type
• Cache decisions to minimize API costs

Cost: Using GPT-4o-mini via OpenRouter, $1 USD = ~5,000+ LLM decisions. Most operations use fast allow/deny (no LLM), so $1 can last 6+ months of heavy use.

This Hook is part of the Claude Fast CC Starterkit. The ultimate Claude Code development kit. Built on Anthropic's official recommendations, resources, and best practices. Constantly evolving. Updated with every release.

Quick Start

npm install -g @abdo-el-mobayad/claude-code-fast-permission-hook
cf-approve install
cf-approve config

Installation

Prerequisites: Node.js 18+ and Claude Code installed

# Step 1: Install globally
npm install -g @abdo-el-mobayad/claude-code-fast-permission-hook

# Step 2: Run the install command to set up the hook
cf-approve install

# Step 3: Configure your API key
cf-approve config

The cf-approve install command will:

1. Locate your Claude Code settings
2. Add the PermissionRequest hook automatically
3. Verify the setup works

Manual Installation

If you prefer to add the hook manually, add this to your Claude Code settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "cf-approve permission"
          }
        ]
      }
    ]
  }
}

Settings file locations:

• User settings: ~/.claude/settings.json
• Project settings: .claude/settings.json
• Project local: .claude/settings.local.json

How It Works

ClaudeFast uses Claude Code's PermissionRequest hook to intercept tool calls before execution:

Claude Code Tool Request → cf-approve → Decision → Execute/Block

Three-Tier Decision System

1. Fast approval for obviously safe operations (Read, Write, Glob, Edit)
2. Fast deny for destructive patterns (rm -rf /, force push to protected branches)
3. LLM analysis for complex operations with intelligent caching

Authentication Options

• OpenRouter (recommended for latency/speed)
• OpenAI API (direct or compatible endpoints)
• Anthropic API (direct Claude access)

Configuration

Quick Setup

# Interactive configuration
cf-approve config

# Check current setup
cf-approve doctor

Manual Configuration

Config is stored at ~/.claude-code-fast-permission-hook/config.json:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKey": "sk-...",
    "baseUrl": "https://openrouter.ai/api/v1"
  },
  "cache": {
    "enabled": true,
    "ttlHours": 168
  },
  "logging": {
    "enabled": true,
    "level": "info"
  }
}

OpenRouter Setup (Recommended)

{
  "llm": {
    "provider": "openai",
    "model": "openai/gpt-4o-mini",
    "apiKey": "sk-or-v1-your-key",
    "baseUrl": "https://openrouter.ai/api/v1"
  },
  "cache": {
    "enabled": true,
    "ttlHours": 168
  }
}

Environment Variables

You can also use environment variables instead of config file:

export OPENAI_API_KEY=sk-your-key
export OPENAI_BASE_URL=https://openrouter.ai/api/v1

What Gets Auto-Approved?

Always Allowed (No LLM call)

• Read operations: Read, Glob, Grep, LS, WebFetch, WebSearch
• Write operations: Write, Edit, MultiEdit, NotebookEdit
• Interaction tools: TodoWrite, Task, AskUserQuestion
• MCP tools: All mcp__* prefixed tools

Always Blocked (No LLM call)

• System destruction: rm -rf /, rm -rf /usr, rm -rf ~
• Protected git branches: git push --force origin main/master/production/staging/develop
• Disk operations: mkfs, fdisk --delete, dd to raw devices, format C:
• Windows destruction: rmdir /s /q C:\, del /f /s /q C:\
• Malicious patterns: Fork bombs, credential theft attempts

LLM Analysis Required

• Bash commands: npm, git (non-force), docker, curl, etc.
• Unknown tools: Any tool not in the allow/deny lists

CLI Commands

cf-approve permission     # Handle PermissionRequest hook (reads stdin)
cf-approve install        # Add hook to Claude Code settings
cf-approve uninstall      # Remove hook from settings
cf-approve config         # Interactive configuration
cf-approve doctor         # Diagnose configuration and connectivity
cf-approve clear-cache    # Clear all cached decisions
cf-approve status         # Show current configuration

Caching Behavior

• Enabled by default for optimal performance
• Working directory scoped for safety across projects
• TTL expiration (default 168 hours / 1 week)
• Caches only definitive decisions (allow/deny from LLM)
• Instant responses for repeated operations

# Clear cache if needed
cf-approve clear-cache

# Disable caching in config
{
  "cache": {
    "enabled": false
  }
}

License

MIT License - see LICENSE file for details.

npm install -g @abdo-el-mobayad/claude-code-fast-permission-hook && cf-approve install && cf-approve config