Skip to main content
hook CX Codex

agent-guard — Claude Code hook: what it does, how to install

This hook checks tool activity for exposed secrets in Claude Code and Codex. It suits projects that need local checks plus Git and CI safeguards.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/settings.json
Open on GitHub

What agent-guard does

agent-guard blocks or masks secret exposure during tool use in Claude Code and Codex. Its hooks run around tool calls, submitted prompts, session startup, and session exit. Checks run locally by default, with no telemetry. PII filtering is optional.

The bundle also includes Git and CI backstops. It watches calls involving Bash, apply_patch, subagents, and MCP tools. When its executable cannot be found, the default open mode lets the action continue; closed mode blocks it. That setting determines what happens when the check itself fails.

For Claude Code, the listed setup uses .claude/settings.json. Codex is also named as a supported platform, while this installation route is specifically for Claude Code.

What it helps with

  • block secret exposure during tool calls
  • mask detected secret values
  • turn on PII filtering for checks
  • check for leaks in Git and CI

Example prompts for the agent

  • Check tool commands for exposed secrets before running them.
  • Review changes made with apply_patch for leaked keys.
  • Enable PII filtering when checking agent activity.

How to install agent-guard

Manually: put the files in place

.claude/settings.json

The hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json

Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command

Questions about agent-guard

How do I install agent-guard in Claude Code?

Configure the hook through .claude/settings.json.

What does the agent-guard hook do?

It blocks or masks secret leaks during tool use in Claude Code and Codex. PII filtering can be enabled separately.

What happens if the checker executable cannot be found?

The default open mode allows the action to continue. Setting AGENT_GUARD_INFRA_FAILURE_MODE=closed makes the hook block it.

Source text

hooks.json · MIT
Hooks bundle shipped with the agent-guard plugin for Claude Code.

Local-by-default, no-telemetry hooks block or mask secret leaks in Claude Code and Codex, with opt-in PII filtering and Git/CI backstops.

Triggers on: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|apply_patch|Agent|Task|mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|*[!0-9.]*) return 1 ;; esac; o=$IFS; IFS=.; set -- $1; IFS=$o; [ \"$#\" -eq 3 ] && [ -n \"$1\" ] && [ -n \"$2\" ] && [ -n \"$3\" ]; }; root_ok() { q=$1; e=${2:-}; z=\"$q/bin/agent-guard\"; [ -x \"$z\" ] && [ -r \"$q/config/gitleaks.toml\" ] && [ -r \"$q/config/deny-read-paths.txt\" ] && [ -r \"$q/config/deny-bash-patterns.txt\" ] || return 1; u=; while IFS= read -r l; do case \"$l\" in VERSION=*) u=${l#VERSION=}; break ;; esac; done <\"$z\"; [ -n \"$u\" ] && { [ -z \"$e\" ] || [ \"$u\" = \"$e\" ]; }; }; if [ -n \"$r\" ]; then v=${r##*/}; semver \"$v\" || v=; if root_ok \"$r\" \"$v\"; then x=\"$r/bin/agent-guard\"; elif [ ! -e \"$r\" ]; then c=\"$b/current\"; t=; [ -L \"$c\" ] && t=$(readlink \"$c\" 2>/dev/null) || :; if semver \"$t\" && root_ok \"$c\" \"$t\"; then x=\"$c/bin/agent-guard\"; else x=$(for z in \"$b\"/*/bin/agent-guard; do [ -x \"$z\" ] || continue; q=${z%/bin/agent-guard}; v=${q##*/}; semver \"$v\" || continue; root_ok \"$q\" \"$v\" || continue; printf \"%s\\\\t%s\\\\n\" \"$v\" \"$z\"; done | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | cut -f 2-); fi; fi; fi; if [ ! -x \"$x\" ]; then mode=${AGENT_GUARD_INFRA_FAILURE_MODE:-open}; case \"$mode\" in closed) action=blocking ;; *) mode=open; action=continuing ;; esac; d=${AGENT_GUARD_WARNING_DIR:-${TMPDIR:-/tmp}/agent-guard-warnings-${UID:-user}}; p=; while IFS= read -r line || [ -n \"$line\" ]; do p=$p$line; done; i=${AGENT_GUARD_SESSION_ID:-}; if [ -z \"$i\" ] && command -v jq >/dev/null 2>&1; then i=$(printf %s \"$p\" | jq -r \".session_id // empty\" 2>/dev/null); fi; if [ -z \"$i\" ]; then case \"$p\" in *\\\"session_id\\\":\\\"*) i=${p#*\\\"session_id\\\":\\\"}; i=${i%%\\\"*}; case \"$i\" in \"\"|*[!A-Za-z0-9._:-]*) i= ;; esac ;; esac; fi; if [ -n \"$i\" ]; then i=$(printf %s \"$i\" | cksum); else i=ppid-${PPID:-0}; fi; k=\"$d/manifest-codex-$i-$mode\"; warn=1; if [ \"$mode\" = open ] && mkdir -p \"$d\" 2>/dev/null; then (umask 077; set -C; : >\"$k\") 2>/dev/null || { [ -e \"$k\" ] && warn=0; }; fi; [ \"$warn\" -eq 0 ] || echo \"agent-guard: PLUGIN_ROOT env not set, selected root was incomplete, or no installed binary was found; $action because AGENT_GUARD_INFRA_FAILURE_MODE=$mode\" >&2; [ \"$mode\" = closed ] && exit 2; exit 0; fi; AGENT_GUARD_HOOK_HOST=codex \"$x\" hook-pre-tool'",
            "timeout": 60
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|apply_patch|Agent|Task|mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|*[!0-9.]*) return 1 ;; esac; o=$IFS; IFS=.; set -- $1; IFS=$o; [ \"$#\" -eq 3 ] && [ -n \"$1\" ] && [ -n \"$2\" ] && [ -n \"$3\" ]; }; root_ok() { q=$1; e=${2:-}; z=\"$q/bin/agent-guard\"; [ -x \"$z\" ] && [ -r \"$q/config/gitleaks.toml\" ] && [ -r \"$q/config/deny-read-paths.txt\" ] && [ -r \"$q/config/deny-bash-patterns.txt\" ] || return 1; u=; while IFS= read -r l; do case \"$l\" in VERSION=*) u=${l#VERSION=}; break ;; esac; done <\"$z\"; [ -n \"$u\" ] && { [ -z \"$e\" ] || [ \"$u\" = \"$e\" ]; }; }; if [ -n \"$r\" ]; then v=${r##*/}; semver \"$v\" || v=; if root_ok \"$r\" \"$v\"; then x=\"$r/bin/agent-guard\"; elif [ ! -e \"$r\" ]; then c=\"$b/current\"; t=; [ -L \"$c\" ] && t=$(readlink \"$c\" 2>/dev/null) || :; if semver \"$t\" && root_ok \"$c\" \"$t\"; then x=\"$c/bin/agent-guard\"; else x=$(for z in \"$b\"/*/bin/agent-guard; do [ -x \"$z\" ] || continue; q=${z%/bin/agent-guard}; v=${q##*/}; semver \"$v\" || continue; root_ok \"$q\" \"$v\" || continue; printf \"%s\\\\t%s\\\\n\" \"$v\" \"$z\"; done | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | cut -f 2-); fi; fi; fi; if [ ! -x \"$x\" ]; then mode=${AGENT_GUARD_INFRA_FAILURE_MODE:-open}; case \"$mode\" in closed) action=blocking ;; *) mode=open; action=continuing ;; esac; d=${AGENT_GUARD_WARNING_DIR:-${TMPDIR:-/tmp}/agent-guard-warnings-${UID:-user}}; p=; while IFS= read -r line || [ -n \"$line\" ]; do p=$p$line; done; i=${AGENT_GUARD_SESSION_ID:-}; if [ -z \"$i\" ] && command -v jq >/dev/null 2>&1; then i=$(printf %s \"$p\" | jq -r \".session_id // empty\" 2>/dev/null); fi; if [ -z \"$i\" ]; then case \"$p\" in *\\\"session_id\\\":\\\"*) i=${p#*\\\"session_id\\\":\\\"}; i=${i%%\\\"*}; case \"$i\" in \"\"|*[!A-Za-z0-9._:-]*) i= ;; esac ;; esac; fi; if [ -n \"$i\" ]; then i=$(printf %s \"$i\" | cksum); else i=ppid-${PPID:-0}; fi; k=\"$d/manifest-codex-$i-$mode\"; warn=1; if [ \"$mode\" = open ] && mkdir -p \"$d\" 2>/dev/null; then (umask 077; set -C; : >\"$k\") 2>/dev/null || { [ -e \"$k\" ] && warn=0; }; fi; [ \"$warn\" -eq 0 ] || echo \"agent-guard: PLUGIN_ROOT env not set, selected root was incomplete, or no installed binary was found; $action because AGENT_GUARD_INFRA_FAILURE_MODE=$mode\" >&2; [ \"$mode\" = closed ] && exit 2; exit 0; fi; AGENT_GUARD_HOOK_HOST=codex \"$x\" hook-post-tool'",
            "timeout": 20
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|*[!0-9.]*) return 1 ;; esac; o=$IFS; IFS=.; set -- $1; IFS=$o; [ \"$#\" -eq 3 ] && [ -n \"$1\" ] && [ -n \"$2\" ] && [ -n \"$3\" ]; }; root_ok() { q=$1; e=${2:-}; z=\"$q/bin/agent-guard\"; [ -x \"$z\" ] && [ -r \"$q/config/gitleaks.toml\" ] && [ -r \"$q/config/deny-read-paths.txt\" ] && [ -r \"$q/config/deny-bash-patterns.txt\" ] || return 1; u=; while IFS= read -r l; do case \"$l\" in VERSION=*) u=${l#VERSION=}; break ;; esac; done <\"$z\"; [ -n \"$u\" ] && { [ -z \"$e\" ] || [ \"$u\" = \"$e\" ]; }; }; if [ -n \"$r\" ]; then v=${r##*/}; semver \"$v\" || v=; if root_ok \"$r\" \"$v\"; then x=\"$r/bin/agent-guard\"; elif [ ! -e \"$r\" ]; then c=\"$b/current\"; t=; [ -L \"$c\" ] && t=$(readlink \"$c\" 2>/dev/null) || :; if semver \"$t\" && root_ok \"$c\" \"$t\"; then x=\"$c/bin/agent-guard\"; else x=$(for z in \"$b\"/*/bin/agent-guard; do [ -x \"$z\" ] || continue; q=${z%/bin/agent-guard}; v=${q##*/}; semver \"$v\" || continue; root_ok \"$q\" \"$v\" || continue; printf \"%s\\\\t%s\\\\n\" \"$v\" \"$z\"; done | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | cut -f 2-); fi; fi; fi; if [ ! -x \"$x\" ]; then mode=${AGENT_GUARD_INFRA_FAILURE_MODE:-open}; case \"$mode\" in closed) action=blocking ;; *) mode=open; action=continuing ;; esac; d=${AGENT_GUARD_WARNING_DIR:-${TMPDIR:-/tmp}/agent-guard-warnings-${UID:-user}}; p=; while IFS= read -r line || [ -n \"$line\" ]; do p=$p$line; done; i=${AGENT_GUARD_SESSION_ID:-}; if [ -z \"$i\" ] && command -v jq >/dev/null 2>&1; then i=$(printf %s \"$p\" | jq -r \".session_id // empty\" 2>/dev/null); fi; if [ -z \"$i\" ]; then case \"$p\" in *\\\"session_id\\\":\\\"*) i=${p#*\\\"session_id\\\":\\\"}; i=${i%%\\\"*}; case \"$i\" in \"\"|*[!A-Za-z0-9._:-]*) i= ;; esac ;; esac; fi; if [ -n \"$i\" ]; then i=$(printf %s \"$i\" | cksum); else i=ppid-${PPID:-0}; fi; k=\"$d/manifest-codex-$i-$mode\"; warn=1; if [ \"$mode\" = open ] && mkdir -p \"$d\" 2>/dev/null; then (umask 077; set -C; : >\"$k\") 2>/dev/null || { [ -e \"$k\" ] && warn=0; }; fi; [ \"$warn\" -eq 0 ] || echo \"agent-guard: PLUGIN_ROOT env not set, selected root was incomplete, or no installed binary was found; $action because AGENT_GUARD_INFRA_FAILURE_MODE=$mode\" >&2; [ \"$mode\" = closed ] && exit 2; exit 0; fi; AGENT_GUARD_HOOK_HOST=codex \"$x\" hook-stop'",
            "timeout": 20
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|
```

© Agent Guard contributors · MIT · hashgraph-online/awesome-codex-plugins

Similar hooks

Hooks catalog →

From the same set391

The whole set →
babok_analyst babok_analyst is a Claude Code hook bundle that manages the BABOK v3 business analysis agent’s session lifecycle and controls MCP tool execution through approval gates. CX Codex ★ 1,596repo stars archcore archcore is a Claude Code hook that brings Git project context into spec-driven development. It runs at session start, before file edits, and after Archcore document operations. CX Codex ★ 1,596repo stars aiboarding aiboarding is a Claude Code and Codex hook that generates, maintains, compresses, and audits AI-agent onboarding files, keeping AGENTS.md and CLAUDE.md current as the codebase changes. CX Codex ★ 1,596repo stars ai-sdlc ai-sdlc — a hook bundle for a six-stage Markdown SDLC in Claude Code. It checks tool calls to block unauthorized file edits and safeguard sensitive project paths. CX Codex ★ 1,596repo stars a-team a-team is a hook for Claude Code that runs at session start and on clear or compact. It displays team status and loads session instructions. CX Codex ★ 1,596repo stars amazon-ads-create-dsp-campaign amazon-ads-create-dsp-campaign walks an Amazon DSP Performance+ or Brand+ campaign from intake to launch: paused setup, ad groups per tactic, then activation after two separate approvals. CX Codex +1 ★ 1,596repo stars returns-reverse-logistics returns-reverse-logistics equips your AI agent with domain logic for RMA authorization, item grading, disposition economics, and return fraud checks. CX Codex +1 ★ 1,596repo stars paid-advertising The paid-advertising skill for Claude Code helps plan and audit paid campaigns against platform rules and benchmarks. It covers Google PMax and AI Max, Meta ads, and retail media. CX Codex +1 ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open