Claude Code Guardian

Validation and permission system for Claude Code focused on controlling what Claude Code can execute, read or write. Allowing users to define a set of rules to evaluate. The system uses Claude Code hooks to enforce the rules.

Features

Security Controls: Block dangerous commands and restrict file access
Performance Optimization: Suggest better alternatives to common tools
Policy Enforcement: Implement organization-wide development policies
Hierarchical Configuration: Multi-layered configuration with team and personal overrides

Quick Setup

1. Install Claude Code Guardian

Install from PyPI using uvx:

uvx claude-code-guardian

Install directly from GitHub using uvx:

uvx --from git+https://github.com/jfpedroza/claude-code-guardian claude-code-guardian

2. Configure Claude Code Hooks

Add the following to your Claude Code settings (.claude/settings.json or ~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "uvx claude-code-guardian hook"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "uvx claude-code-guardian hook"
          }
        ]
      }
    ]
  }
}

3. Test Installation

# Should show help and available commands
uvx claude-code-guardian

# View current configuration and rules
uvx claude-code-guardian rules

Configuration

Configuration Hierarchy

The system loads configuration from multiple sources in this order (later sources override earlier ones):

Default Rules: Built-in rules shipped with the package
User Config: ~/.config/claude-code-guardian/config.yml (or custom via $CLAUDE_CODE_GUARDIAN_CONFIG/config.yml)
Project Shared: .claude/guardian/config.yml (committed to version control)
Project Local: .claude/guardian/config.local.yml (personal overrides, should be in .gitignore)

Configuration Format

# Enable or disable built-in default rules
default_rules: true  # or false, or list of glob patterns like ["security.*"]

rules:
  security.dangerous_commands:
    type: pre_use_bash
    pattern: "rm -rf|sudo rm"
    action: deny
    message: "Dangerous command detected"
    priority: 100
    enabled: true

  security.git_operations:
    type: pre_use_bash
    action: ask
    priority: 90
    message: "Git command requires confirmation"
    commands:
      - pattern: "git push$"
        action: allow
        message: "Standard git push allowed"
      - pattern: "git push origin"
        action: allow
        message: "Push to origin allowed"
      - pattern: "git push.*--force"
        action: ask
        message: "Force push requires confirmation"
    enabled: true

  performance.grep_alternative:
    type: pre_use_bash
    pattern: "^grep\\b(?!.*\\|)"
    action: deny
    message: "Use 'rg' (ripgrep) for better performance"
    priority: 50
    enabled: true

  security.env_files:
    type: path_access
    pattern: "**/*.env*"
    scope: read_write
    action: deny
    message: "Access to environment files blocked"
    priority: 80
    enabled: true

  security.sensitive_paths:
    type: path_access
    action: warn  # default action
    priority: 70
    paths:
      - pattern: "**/.git/**"
        scope: write
        action: warn
        message: "Direct .git manipulation detected"
      - pattern: "**/config/secrets/**"
        scope: read
        action: deny
        message: "Access to secrets directory blocked"
    enabled: true

Configuration Merging Behavior

Rule ID System

Rule IDs: Descriptive names with dot notation (e.g., security.dangerous_command, performance.suggestions), but any name works
Merging: Rules with same ID are merged, with later configs overriding earlier ones

Merge Strategy

Rules with the same ID are merged together
Any field except type can be overridden
Lists (paths, commands) are replaced entirely, not merged
Configuration hierarchy: default → user → shared → local

Priority System

Higher priority number = more specific = evaluated first
Same priority: Evaluation order is undefined
Rule evaluation: First matching rule determines the action
Pattern evaluation: Within a rule's commands or paths list, patterns are evaluated in the order they appear

Default Rules

Claude Code Guardian comes with built-in default rules that provide basic security and performance optimizations. All default rules have a priority of 30. Only security rules are enabled by default.

You can enable all default rules by setting default_rules: true in your configuration, disable them with default_rules: false or enable specific categories using patterns like default_rules: ["performance.*"].

Rule ID	Type	Description
`security.git_access`	`path_access`	Blocks direct write access to `.git` directories
`security.git_commands`	`pre_use_bash`	Prevents `git push --force`, suggests `--force-with-lease` instead
`performance.grep_suggestion`	`pre_use_bash`	Suggests using `rg` (ripgrep) instead of `grep`
`performance.find_suggestion`	`pre_use_bash`	Suggests using ripgrep file search instead of `find -name` commands

View Complete Default Rules: ccguardian/config/default.yml

Note: Current default rules are mostly there to test the system. Suggestions are welcome on what should be included by default.

Rule Types

`pre_use_bash` - Bash Command Validation

Validates commands before the Bash tool executes them.

Hook Types: PreToolUse Tool Names: Bash Trigger Condition: When pattern matches against command Context Access: tool_input.command Pattern Type: Regex

Single Pattern Format:

rule_name:
  type: pre_use_bash
  pattern: "regex_pattern"
  action: deny|allow|ask|warn|halt|continue
  message: "Custom message"
  priority: 100
  enabled: true

Multiple Commands Format:

rule_name:
  type: pre_use_bash
  action: ask  # default action
  message: "Default message"
  priority: 100
  commands:
    - pattern: "specific_pattern"
      action: allow
      message: "Override message"
    - pattern: "another_pattern"
      action: deny
  enabled: true

Fields:

type: Required, must be pre_use_bash
pattern OR commands: Required (mutually exclusive in config)
- pattern: Single regex pattern (converted to commands list of one element internally)
- commands: List of command patterns with individual actions and priorities
action: Default action for rule (default: continue)
message: Default message (optional)
priority: Rule priority for evaluation order (default: 50)
enabled: Whether rule is active (default: true)

`path_access` - File System Access Control

Controls access to files and directories for Read, Edit, MultiEdit, and Write tools.

Hook Types: PreToolUse Tool Names: Read, Edit, MultiEdit, Write Trigger Condition: When tool accesses matching path Context Access: tool_input.file_path Pattern Type: Glob

Single Pattern Format:

rule_name:
  type: path_access
  pattern: "glob_pattern"
  scope: read|write|read_write
  action: deny|allow|ask|warn|halt|continue
  message: "Custom message"
  priority: 100
  enabled: true

Multiple Paths Format:

rule_name:
  type: path_access
  action: deny  # default action
  priority: 100
  paths:
    - pattern: "**/.git/**"
      scope: write
      action: warn
      message: "Git directory write access"
    - pattern: "**/secrets/**"
      scope: read_write
      action: deny
      message: "Secrets access blocked"
  enabled: true

Fields:

type: Required, must be path_access
pattern OR paths: Required (mutually exclusive in config)
- pattern: Single glob pattern (converted to paths list of one element internally)
- paths: List of path patterns with individual scopes, actions, and messages
scope: Access scope - read, write, or read_write (default: read_write)
action: Default action for rule (default: deny)
message: Default message (optional)
priority: Rule priority for evaluation order (default: 50)
enabled: Whether rule is active (default: true)

Actions

allow: Permit operation silently
warn: Show warning but allow operation
ask: Require user confirmation
deny: Block operation completely
halt: Stop all processing
continue: Do nothing, let Claude's default permission system run

Scopes (path_access only)

read: Apply to read operations only (Read tool)
write: Apply to write operations only (Edit, MultiEdit, Write tools)
read_write: Apply to both read and write operations (default)

CLI Commands