Terminal
Terminal/Skill
Sets up ggshield as a git commit or push hook, or as a Claude Code, Cursor, Copilot, or Codex hook, to block secrets.
By GitGuardian
Works with
npx skills add gitguardian/agent-skills --skill install-hooksggshield install wires ggshield in as a hook so hardcoded secrets are caught before they
leak. This is the prevention layer — the reactive skills (scan-secrets, scan-machine,
check-hmsl) find secrets that already exist; this one stops new ones at the door.
It installs two distinct families of hook:
pre-commit / pre-push. Catch a secret as it is committed or pushed and block
the git operation, so it never enters history.claude-code, codex, copilot, cursor, vscode. Register
ggshield inside an AI coding tool so it scans the tool's prompts, actions, and outputs in real
time: it scans your prompt before it reaches the model, scans commands, file reads, and MCP calls
before the agent runs them, and scans outputs — blocking the prompt or action when a secret is
found.Both families install local (this project only) or global (all projects). Global is system-modifying — get explicit consent first.
Install a hook when:
Do not use this skill to scan code that already exists — that is scan-secrets. A hook only
guards future commits, pushes, or AI-tool interactions.
ggshield install covers two families. Route by what the user said — do not guess across families:
| The request mentions… | Install this family | Hook type |
|---|---|---|
| "Claude" / "Claude Code" | AI-assistant | claude-code |
| "Cursor" | AI-assistant | cursor |
| "Copilot" / "VS Code" | AI-assistant | copilot / vscode |
| "Codex" | AI-assistant | codex |
| "AI assistant" / "agent" hook generically | AI-assistant | ask which tool |
| "pre-commit" / "pre-push" / "git hook" | git | pre-commit / pre-push |
| "block secrets from being committed / pushed", "stop secrets entering history" | git | pre-commit / pre-push |
If the request is bare — e.g. "install hooks" with no family signal — STOP and ask which family before running anything. Present the two one-liners:
Once the family is clear, walk the within-family choices under Choosing your hook.
Every hook calls the GitGuardian API to scan content, so ggshield must be installed and
authenticated before any hook will work. An unauthenticated hook fails on every commit or
AI-tool action.
ggshield --version must succeed. AI-assistant hooks need ggshield 1.49.0+ (1.51.0+ for
codex).ggshield api-status must report a working API key.If either check fails, complete the setup steps in
references/ggshield-cli-setup.md (install ggshield, then
ggshield auth login) before installing any hook.
Once the family is settled, walk the user through the within-family choices. Do not assume a default — present the trade-offs and let the user choose.
1. Stage — pre-commit or pre-push?
| Stage | Catches | Trade-off |
|---|---|---|
pre-commit | Earliest — blocks the git commit itself | Tightest. Cannot create even a local commit containing a secret. |
pre-push | Before anything leaves the machine | Allows local WIP commits with secrets; only blocks on push. |
2. Scope — local or global?
| Scope | Applies to | Trade-off |
|---|---|---|
--mode local | The current repository only | Contained, easy to reason about and remove. |
--mode global | Every repo cloned/init'd afterward (git template dir) | Maximum coverage. Modifies the user's global git config — get explicit consent. |
Scope — local or global? Same present-the-choice discipline as git hooks.
| Scope | Applies to | Writes to (Claude Code example) |
|---|---|---|
--mode local | The current project only | the project's .claude/settings.json |
--mode global | All projects, for this user | the user-level ~/.claude/settings.json |
Global mode is system-modifying for both families. Confirm with the user before installing a global hook; never install one silently.
Pick the family and combination the user chose.
# Local pre-commit hook (this repo only)
ggshield install -m local -t pre-commit
# Local pre-push hook
ggshield install -m local -t pre-push
# Global pre-commit hook (all future repos) — only after explicit user consent
ggshield install -m global -t pre-commit
# Claude Code hook, this project only
ggshield install -m local -t claude-code
# Cursor hook, all projects (user-level) — system-modifying, confirm first
ggshield install -m global -t cursor
# Other tools: -t copilot, -t vscode, -t codex
Which file each AI-assistant hook writes:
| Tool | -t value | Config file |
|---|---|---|
| Claude Code | claude-code | .claude/settings.json (local) or ~/.claude/settings.json (global) |
| Cursor | cursor | .cursor/hooks.json |
| GitHub Copilot / VS Code | copilot / vscode | VS Code settings |
| Codex | codex | ~/.codex/hooks.json |
Useful flags (both families):
-f, --force — overwrite an existing hook script/config entry of the same type.-a, --append — append ggshield to an existing hook instead of overwriting. Use when the repo
or tool already has a hook you must not clobber.After running ggshield install, confirm it landed:
0..git/hooks/pre-commit or .git/hooks/pre-push in the repo.git config --get init.templateDir).ggshield (e.g. a ggshield entry in
.claude/settings.json, .cursor/hooks.json, or ~/.codex/hooks.json).This confirms installation, not live detection. It does not scan existing code or prove a real
secret would be caught — it proves the hook is wired in. To scan code you already have, use the
scan-secrets skill.
When a git hook fires, ggshield prints the detected secret's type and location and aborts the
git commit (pre-commit) or git push (pre-push). When an AI-assistant hook fires, it blocks
the prompt or the agent's action before it runs. Either way the content has not reached any
remote — this is the easiest case to remediate, the pre-leak track:
.env that is gitignored).No rotation is required — the secret never left your perimeter, so it has not leaked.
If the workspace has a custom remediation workflow, ggshield (≥ 1.30.0) prints the organization's own remediation message in the block output (configured per touchpoint under GitGuardian → Remediation workflow → Pre-commit / Pre-push / Pre-receive). That message is the customer's security team's process and takes the lead — surface it to the user verbatim as the primary guidance, then follow the remove-and-recommit steps above to fill in around it. Do not replace it with generic advice.
If, instead, you discover a secret that is already in git history (committed before the hook
existed, or already pushed), that is a different, harder situation: the secret is exposed and must
be treated as compromised. Use the scan-secrets skill, which carries the full remediation
doctrine for secrets that are already in history or already public.
--append, not --force, when a hook already exists, unless the user confirms the
existing hook is disposable. --force overwrites it.scan-secrets. It guards future commits, pushes, and AI-tool
interactions only; existing code and history still need a scan.ggshield. Run ggshield api-status; if it fails, complete the setup in
references/ggshield-cli-setup.md.ggshield install says a hook already exists. Re-run with -a, --append to add ggshield
alongside the existing hook, or -f, --force to replace it (destructive — confirm first)..claude/settings.json, .cursor/hooks.json, ~/.codex/hooks.json,
or VS Code settings); confirm ggshield 1.49.0+ (1.51.0+ for codex)..git/hooks/<type>; for global mode confirm git config --get init.templateDir points where the
hook was written and that the repo was created/cloned after the global install.git commit --no-verify skips hooks. Use only
when you are certain there is no secret; it defeats the protection..git/hooks/ (local) or the template dir
(global); for AI-assistant hooks, remove the ggshield entry from the tool's config file. There
is no ggshield uninstall.