agent-guard

Agent Guard

Stop your AI coding agent from leaking secrets — in real time, before the tool call runs.

Agent Guard is a deterministic guardrail for AI coding agents (Claude Code, Codex) and the Git hooks, CI, and CLI around them. It blocks common ways an agent accidentally exposes secrets: reading .env, writing secret-like values, running shell commands that dump credentials, or leaving secrets in the working tree after a tool call. It uses gitleaks for detection and plain shell scripts for integration.

Unlike commit- or CI-time scanners that catch a leak after it lands, Agent Guard also runs at the agent's tool boundary — the .env read or secret write is blocked before it happens. Pair it with commit/CI scanning for defense in depth.

It is not a vault, credential rotator, or replacement for GitHub Secret Scanning / Push Protection.

Quick start (Claude Code)

Install from the marketplace:

/plugin marketplace add JeongJaeSoon/agent-guard
/plugin install agent-guard@agent-guard
/reload-plugins

Verify it's live — ask the agent to read your .env:

Please read .env

It should refuse:

agent-guard: blocked sensitive file access: .env

Detection needs jq and gitleaks on your machine (brew install jq gitleaks; see Requirements for Linux). Using Codex, Git hooks, or CI instead? Pick your path below.

Pick an install path

Use case	Install path	Best first check
Claude Code agent guardrails	Quick start (Claude Code)	Ask the agent to read .env; it should be blocked.
Codex stable guardrails	Codex direct CLI + Git hook	Run agent-guard smoke-test; commit a staged fixture secret, and it should fail.
Codex experimental plugin hooks	Codex plugin	Enable plugin_hooks, trust hooks in /hooks, then ask Codex to read .env; it should be blocked.
Local commits	Native Git hook	Commit a staged fixture secret; commit should fail.
CI / PRs	GitHub Actions	Push a test PR with a gitleaks-detectable fixture; workflow should fail.
Manual scans	Direct CLI	Run agent-guard smoke-test.

Requirements

Agent Guard runs on macOS and Linux and expects:

• sh
• awk
• git
• jq
• gitleaks 8.30 or newer recommended

Install paths that download release archives also use curl, tar, shasum, and ln. PII endpoint providers also use curl.

With a direct CLI install:

agent-guard setup   # prints dependency status and install hints
agent-guard check   # strict pass/fail dependency check
agent-guard smoke-test

From a clone of this repo:

plugins/agent-guard/bin/agent-guard setup
make check
make smoke-test

The Claude Code and Codex plugin installs do not put agent-guard on your shell PATH; install jq and gitleaks with your package manager for those paths:

brew install jq gitleaks

On Debian / Ubuntu or Fedora, install jq with the system package manager and download gitleaks from its release page.

Claude Code Plugin

Install and verify in Quick start (Claude Code). Useful slash commands once installed:

/agent-guard:verify
/agent-guard:checksum [VERSION]

Codex Plugin

Use the direct CLI plus the native Git hook as the stable Codex path:

curl -fsSL https://github.com/JeongJaeSoon/agent-guard/releases/latest/download/bootstrap.sh | sh
agent-guard scan-working-tree
~/.agent-guard/install.sh git-hooks

That path gives you on-demand scans and commit-time blocking.

Codex plugin hooks are still behind an under-development Codex feature flag. If you accept that warning and want pre-tool read/write/bash guardrails, enable plugin hooks and install from the marketplace:

codex features enable plugin_hooks
codex plugin marketplace add JeongJaeSoon/agent-guard

Then open /plugins in the Codex TUI, install Agent Guard, restart Codex, open /hooks, and trust the PreToolUse, PostToolUse, and Stop hooks.

Smoke test:

Please read .env

Expected result:

agent-guard: blocked sensitive file access: .env