command-guard

command-guard

Configurable guardrails for Claude Code - block commands, protect files, enforce workflows.

Overview

command-guard is a Claude Code plugin that provides configurable guardrails for blocking or warning about tool usage. It ships with no default rules - all configuration comes from your project's config file.

Installation

Add the GitHub repo as a plugin marketplace, then install:

claude plugin marketplace add golergka/command-guard
claude plugin install command-guard@golergka-command-guard

For local development/testing:

claude --plugin-dir /path/to/command-guard

Plugins

This repository contains multiple independent plugins. Install only what you need:

Plugin	Description	Install command
command-guard	Configurable rules to block or warn about tool usage	claude plugin install command-guard@golergka-command-guard
commit-guard	Prevents Claude from finishing with uncommitted changes	claude plugin install commit-guard@golergka-command-guard

---

command-guard

Configuration

Create .claude/command-guard.json in your project root:

{
  "rules": [
    {
      "match": "command",
      "pattern": "git\\s+reset\\s+--hard",
      "message": "git reset --hard destroys uncommitted changes. Use git stash first.",
      "severity": "error"
    },
    {
      "match": "file_path",
      "pattern": "patches/.*\\.patch$",
      "message": "Patch files should not be edited directly. Use pnpm patch workflow.",
      "severity": "error"
    },
    {
      "match": "tool_name",
      "pattern": "mcp__betterstack__",
      "message": "Consider using better-stack-logs agent for context isolation.",
      "severity": "warning"
    }
  ],
  "safePatterns": ["git\\s+checkout\\s+-b\\s"]
}

If no config file exists, all tool uses are allowed (empty rules = no blocking).

Rule Schema

Field	Required	Type	Description
match	Yes	"command" | "file_path" | "tool_name"	What to match against
pattern	Yes	string (regex)	Pattern to match
message	Yes	string	Message shown when triggered
severity	Yes	"error" | "warning"	error=block, warning=reminder
case_sensitive	No	boolean	Default: false

Match Types

command

Matches against Bash command content. Commands are:

• Split on chain operators (&&, ||, ;, |)
• Normalized (absolute paths like /usr/bin/git become git)
• Stripped of quoted strings to avoid false positives

file_path

Matches against file paths in Edit and Write tool calls.

tool_name

Matches against the tool name. Useful for MCP tools like mcp__betterstack__telemetry_query.

Severity Levels

error

Blocks the tool use entirely. The user sees a block message and the tool doesn't execute.

BLOCKED: git reset --hard destroys all uncommitted changes permanently. Use 'git stash' first.

Context: git reset --hard HEAD~1

To override, add a comment: # OVERRIDE: <reason>

warning

Shows a reminder after the tool completes (PostToolUse). Doesn't block execution.

Warnings are throttled per (working directory, Claude session, rule) — by default, each rule surfaces on hit #1, #11, #21, … for a given session and folder. Intermediate hits are silently suppressed so a noisy rule doesn't flood the conversation. Errors are never throttled.

Override the interval with the top-level warningThrottle field in .claude/command-guard.json (default 10, set to 1 to disable throttling):

{
  "warningThrottle": 10,
  "rules": [ ... ]
}

Counter state lives in ~/.claude/command-guard/throttle/<session_id>.json and is pruned automatically once the directory grows past ~50 sessions.

Safe Patterns

The safePatterns array contains regex patterns that bypass blocking rules. This is useful for allowing safe variants of otherwise dangerous commands:

{
  "safePatterns": [
    "git\\s+checkout\\s+-b\\s",
    "git\\s+restore\\s+--staged",
    "git\\s+push\\s+--force-with-lease"
  ]
}

Override Mechanism

Any blocked command can be overridden by adding a comment with explicit reasoning:

git reset --hard  # OVERRIDE: cleaning up failed rebase state

The reason must be at least 5 characters. Override usage is logged to stderr.

Examples

Block Destructive Git Commands