{"id":31537700,"url":"https://github.com/jfpedroza/claude-code-guardian","last_synced_at":"2025-10-04T08:10:16.066Z","repository":{"id":309647367,"uuid":"1031116072","full_name":"jfpedroza/claude-code-guardian","owner":"jfpedroza","description":"Validation and permission system for Claude Code","archived":false,"fork":false,"pushed_at":"2025-08-25T07:51:28.000Z","size":147,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-08T23:53:26.640Z","etag":null,"topics":["agentic-ai","claude","claude-code","hooks"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/claude-code-guardian/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jfpedroza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-03T03:34:55.000Z","updated_at":"2025-08-29T01:40:22.000Z","dependencies_parsed_at":"2025-08-13T03:55:26.545Z","dependency_job_id":"57b49c49-f89a-4db6-b601-c0153e798c32","html_url":"https://github.com/jfpedroza/claude-code-guardian","commit_stats":null,"previous_names":["jfpedroza/claude-code-guardian"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jfpedroza/claude-code-guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfpedroza%2Fclaude-code-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfpedroza%2Fclaude-code-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfpedroza%2Fclaude-code-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfpedroza%2Fclaude-code-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jfpedroza","download_url":"https://codeload.github.com/jfpedroza/claude-code-guardian/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfpedroza%2Fclaude-code-guardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276930213,"owners_count":25730344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","claude","claude-code","hooks"],"created_at":"2025-10-04T08:10:13.643Z","updated_at":"2025-10-04T08:10:16.061Z","avatar_url":"https://github.com/jfpedroza.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Guardian\n\nValidation and permission system for Claude Code focused on controlling what Claude Code\ncan execute, read or write. Allowing users to define a set of rules to evaluate.\nThe system uses Claude Code hooks to enforce the rules.\n\n## Features\n\n- **Security Controls**: Block dangerous commands and restrict file access\n- **Performance Optimization**: Suggest better alternatives to common tools\n- **Policy Enforcement**: Implement organization-wide development policies\n- **Hierarchical Configuration**: Multi-layered configuration with team and personal overrides\n\n## Quick Setup\n\n### 1. Install Claude Code Guardian\n\nInstall from PyPI using `uvx`:\n\n```bash\nuvx claude-code-guardian\n```\n\nInstall directly from GitHub using `uvx`:\n\n```bash\nuvx --from git+https://github.com/jfpedroza/claude-code-guardian claude-code-guardian\n```\n\n### 2. Configure Claude Code Hooks\n\nAdd the following to your Claude Code settings (`.claude/settings.json` or `~/.claude/settings.json`):\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"uvx claude-code-guardian hook\"\n          }\n        ]\n      }\n    ],\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"uvx claude-code-guardian hook\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### 3. Test Installation\n\n```bash\n# Should show help and available commands\nuvx claude-code-guardian\n\n# View current configuration and rules\nuvx claude-code-guardian rules\n```\n\n## Configuration\n\n### Configuration Hierarchy\n\nThe system loads configuration from multiple sources in this order (later sources override earlier ones):\n\n1. **Default Rules**: Built-in rules shipped with the package\n2. **User Config**: `~/.config/claude-code-guardian/config.yml` (or custom via `$CLAUDE_CODE_GUARDIAN_CONFIG/config.yml`)\n3. **Project Shared**: `.claude/guardian/config.yml` (committed to version control)\n4. **Project Local**: `.claude/guardian/config.local.yml` (personal overrides, should be in `.gitignore`)\n\n### Configuration Format\n\n```yaml\n# Enable or disable built-in default rules\ndefault_rules: true  # or false, or list of glob patterns like [\"security.*\"]\n\nrules:\n  security.dangerous_commands:\n    type: pre_use_bash\n    pattern: \"rm -rf|sudo rm\"\n    action: deny\n    message: \"Dangerous command detected\"\n    priority: 100\n    enabled: true\n\n  security.git_operations:\n    type: pre_use_bash\n    action: ask\n    priority: 90\n    message: \"Git command requires confirmation\"\n    commands:\n      - pattern: \"git push$\"\n        action: allow\n        message: \"Standard git push allowed\"\n      - pattern: \"git push origin\"\n        action: allow\n        message: \"Push to origin allowed\"\n      - pattern: \"git push.*--force\"\n        action: ask\n        message: \"Force push requires confirmation\"\n    enabled: true\n\n  performance.grep_alternative:\n    type: pre_use_bash\n    pattern: \"^grep\\\\b(?!.*\\\\|)\"\n    action: deny\n    message: \"Use 'rg' (ripgrep) for better performance\"\n    priority: 50\n    enabled: true\n\n  security.env_files:\n    type: path_access\n    pattern: \"**/*.env*\"\n    scope: read_write\n    action: deny\n    message: \"Access to environment files blocked\"\n    priority: 80\n    enabled: true\n\n  security.sensitive_paths:\n    type: path_access\n    action: warn  # default action\n    priority: 70\n    paths:\n      - pattern: \"**/.git/**\"\n        scope: write\n        action: warn\n        message: \"Direct .git manipulation detected\"\n      - pattern: \"**/config/secrets/**\"\n        scope: read\n        action: deny\n        message: \"Access to secrets directory blocked\"\n    enabled: true\n```\n\n### Configuration Merging Behavior\n\n#### Rule ID System\n\n- **Rule IDs**: Descriptive names with dot notation (e.g., `security.dangerous_command`, `performance.suggestions`),\nbut any name works\n- **Merging**: Rules with same ID are merged, with later configs overriding earlier ones\n\n#### Merge Strategy\n\n- Rules with the same ID are merged together\n- Any field except `type` can be overridden\n- Lists (`paths`, `commands`) are replaced entirely, not merged\n- Configuration hierarchy: default → user → shared → local\n\n#### Priority System\n\n1. **Higher priority number = more specific = evaluated first**\n2. **Same priority**: Evaluation order is undefined\n3. **Rule evaluation**: First matching rule determines the action\n4. **Pattern evaluation**: Within a rule's `commands` or `paths` list, patterns are evaluated in the order they appear\n\n## Default Rules\n\nClaude Code Guardian comes with built-in default rules that provide basic security and performance optimizations.\nAll default rules have a priority of 30. Only security rules are enabled by default.\n\nYou can enable all default rules by setting `default_rules: true` in your configuration,\ndisable them with `default_rules: false` or enable specific categories using patterns like `default_rules: [\"performance.*\"]`.\n\n| Rule ID | Type | Description |\n|---------|------|-------------|\n| `security.git_access` | `path_access` | Blocks direct write access to `.git` directories |\n| `security.git_commands` | `pre_use_bash` | Prevents `git push --force`, suggests `--force-with-lease` instead |\n| `performance.grep_suggestion` | `pre_use_bash` | Suggests using `rg` (ripgrep) instead of `grep` |\n| `performance.find_suggestion` | `pre_use_bash` | Suggests using ripgrep file search instead of `find -name` commands |\n\n**View Complete Default Rules:** [ccguardian/config/default.yml](https://github.com/jfpedroza/claude-code-guardian/blob/main/ccguardian/config/default.yml)\n\n**Note**: Current default rules are mostly there to test the system. Suggestions are welcome on what should be included\nby default.\n\n## Rule Types\n\n### `pre_use_bash` - Bash Command Validation\n\nValidates commands before the Bash tool executes them.\n\n**Hook Types:** `PreToolUse`\n**Tool Names:** `Bash`\n**Trigger Condition:** When pattern matches against command\n**Context Access:** `tool_input.command`\n**Pattern Type:** Regex\n\n**Single Pattern Format:**\n\n```yaml\nrule_name:\n  type: pre_use_bash\n  pattern: \"regex_pattern\"\n  action: deny|allow|ask|warn|halt|continue\n  message: \"Custom message\"\n  priority: 100\n  enabled: true\n```\n\n**Multiple Commands Format:**\n\n```yaml\nrule_name:\n  type: pre_use_bash\n  action: ask  # default action\n  message: \"Default message\"\n  priority: 100\n  commands:\n    - pattern: \"specific_pattern\"\n      action: allow\n      message: \"Override message\"\n    - pattern: \"another_pattern\"\n      action: deny\n  enabled: true\n```\n\n**Fields:**\n\n- **`type`**: Required, must be `pre_use_bash`\n- **`pattern` OR `commands`**: Required (mutually exclusive in config)\n  - **`pattern`**: Single regex pattern (converted to `commands` list of one element internally)\n  - **`commands`**: List of command patterns with individual actions and priorities\n- **`action`**: Default action for rule (default: `continue`)\n- **`message`**: Default message (optional)\n- **`priority`**: Rule priority for evaluation order (default: 50)\n- **`enabled`**: Whether rule is active (default: `true`)\n\n### `path_access` - File System Access Control\n\nControls access to files and directories for Read, Edit, MultiEdit, and Write tools.\n\n**Hook Types:** `PreToolUse`\n**Tool Names:** `Read`, `Edit`, `MultiEdit`, `Write`\n**Trigger Condition:** When tool accesses matching path\n**Context Access:** `tool_input.file_path`\n**Pattern Type:** Glob\n\n**Single Pattern Format:**\n\n```yaml\nrule_name:\n  type: path_access\n  pattern: \"glob_pattern\"\n  scope: read|write|read_write\n  action: deny|allow|ask|warn|halt|continue\n  message: \"Custom message\"\n  priority: 100\n  enabled: true\n```\n\n**Multiple Paths Format:**\n\n```yaml\nrule_name:\n  type: path_access\n  action: deny  # default action\n  priority: 100\n  paths:\n    - pattern: \"**/.git/**\"\n      scope: write\n      action: warn\n      message: \"Git directory write access\"\n    - pattern: \"**/secrets/**\"\n      scope: read_write\n      action: deny\n      message: \"Secrets access blocked\"\n  enabled: true\n```\n\n**Fields:**\n\n- **`type`**: Required, must be `path_access`\n- **`pattern` OR `paths`**: Required (mutually exclusive in config)\n  - **`pattern`**: Single glob pattern (converted to `paths` list of one element internally)\n  - **`paths`**: List of path patterns with individual scopes, actions, and messages\n- **`scope`**: Access scope - `read`, `write`, or `read_write` (default: `read_write`)\n- **`action`**: Default action for rule (default: `deny`)\n- **`message`**: Default message (optional)\n- **`priority`**: Rule priority for evaluation order (default: 50)\n- **`enabled`**: Whether rule is active (default: `true`)\n\n## Actions\n\n- **`allow`**: Permit operation silently\n- **`warn`**: Show warning but allow operation\n- **`ask`**: Require user confirmation\n- **`deny`**: Block operation completely\n- **`halt`**: Stop all processing\n- **`continue`**: Do nothing, let Claude's default permission system run\n\n## Scopes (path_access only)\n\n- **`read`**: Apply to read operations only (Read tool)\n- **`write`**: Apply to write operations only (Edit, MultiEdit, Write tools)\n- **`read_write`**: Apply to both read and write operations (default)\n\n## CLI Commands\n\n### `claude-code-guardian`\n\nMain entry point. Shows help when run without arguments.\n\n```bash\n# Show help\nclaude-code-guardian\nclaude-code-guardian -h\nclaude-code-guardian --help\n```\n\n### `claude-code-guardian hook`\n\nHook execution entry point called by Claude Code.\n\n```bash\n# Standard execution (used by Claude Code hooks)\nclaude-code-guardian hook\n\n# Verbose logging for debugging\nclaude-code-guardian hook --verbose\nclaude-code-guardian hook -v\n```\n\n### `claude-code-guardian rules`\n\nDisplay configuration diagnostics and rule information.\n\n```bash\n# Show complete configuration and rules\nclaude-code-guardian rules\n\n# Verbose output with debug information\nclaude-code-guardian rules --verbose\nclaude-code-guardian rules -v\n```\n\n**Sample Output:**\n\n```text\nConfiguration Sources:\n✓ Default: /usr/local/lib/python3.12/site-packages/ccguardian/config/default.yml\n✓ User:    ~/.config/claude-code-guardian/config.yml\n✗ Shared:  .claude/guardian/config.yml\n✓ Local:   .claude/guardian/config.local.yml\n✗ Environment: CLAUDE_CODE_GUARDIAN_CONFIG (not set)\n\nMerged Configuration:\n====================\nDefault Rules: enabled\nTotal Rules: 15\nActive Rules: 13 (2 disabled)\n\nRule Evaluation Order (by priority):\n=====================\n\nID: security.dangerous_commands | Type: pre_use_bash | Priority: 100\nCommands:\n- `rm -rf|sudo rm` (action: deny)\n\nID: security.git_operations | Type: pre_use_bash | Priority: 90\nCommands:\n- `git push.*--force` (action: ask)\n- `git push origin` (action: allow)\n- `git push$` (action: allow)\n\nID: security.env_files | Type: path_access | Priority: 80\nPaths:\n- `**/*.env*` [read_write] (action: deny)\n\nDisabled Rules:\n==============\nID: performance.grep_alternative | Type: pre_use_bash\nID: security.temp_files | Type: path_access\n```\n\n## Environment Variables\n\n- **`CLAUDE_CODE_GUARDIAN_CONFIG`**: Override user-level config directory\n  - Default: `~/.config/claude-code-guardian/`\n  - Example: `export CLAUDE_CODE_GUARDIAN_CONFIG=\"/custom/config/path\"`\n\n- **`CLAUDE_PROJECT_DIR`**: Project directory (automatically set by Claude Code)\n  - Used to locate `.claude/guardian/` configuration files\n\n## Development\n\n### Requirements\n\n- Python 3.12+\n- Dependencies: `cchooks`, `click`, `PyYAML`\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/jfpedroza/claude-code-guardian.git\ncd claude-code-guardian\n\n# Install dependencies\nuv sync\n\n# Test installation\nuv run claude-code-guardian --help\nuv run claude-code-guardian rules\n\n# Run tests\nuv run pytest\n```\n\n## Debugging \u0026 Troubleshooting\n\n### Log Files\n\nClaude Code Guardian logs all activity to a rotating log file located at:\n\n- **Linux/macOS**: `~/.local/share/claude-code-guardian/guardian.log`\n- **Windows**: `%LOCALAPPDATA%/claude-code-guardian/guardian.log`\n\nLog files are automatically rotated when they reach 10MB, keeping the last 5 files.\n\n### Enable Debug Logging\n\nUse the `--verbose` flag to enable debug-level logging:\n\n```bash\n# Enable verbose logging for hook execution\nclaude-code-guardian hook --verbose\n\n# Enable verbose logging for rules command\nclaude-code-guardian rules --verbose\n```\n\n### Check Configuration\n\nView your complete configuration and rule evaluation order:\n\n```bash\nclaude-code-guardian rules\n```\n\n### Verify Hook Setup\n\nEnsure your Claude Code `settings.json` includes the hook configuration for both\n`SessionStart` and `PreToolUse` events.\n\n### Common Issues\n\n1. **\"Command not found\"**: Ensure `uvx` installation was successful\n2. **\"No rules active\"**: Check configuration files exist and contain valid YAML\n3. **\"Permission denied\"**: Verify file permissions on configuration directories\n4. **\"Hook not executing\"**: Confirm Claude Code hooks are properly configured\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfpedroza%2Fclaude-code-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfpedroza%2Fclaude-code-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfpedroza%2Fclaude-code-guardian/lists"}