Secret scanning for AI coding tools
Developers increasingly rely on AI coding tools like Cursor, Claude Code, and Codex to write and modify code. These tools can inadvertently expose secrets: a developer might paste credentials into a prompt, or the AI agent might read a file or run a command that contains API keys or tokens. Once a secret reaches the AI model, it may be logged, cached, or sent to third-party services.
ggshield integrates with AI coding tools through their hook systems to scan interactions in real time. When a secret is detected, ggshield blocks the action before it reaches the model and tells the developer to remove the secret.
How it works
AI coding tools support hooks: custom commands that run at specific points during an AI interaction. ggshield registers as a hook and scans content at three stages:
| Stage | What it does | Behavior |
|---|---|---|
| Prompt submission | Scans the user's prompt before it is sent to the AI model | Blocks the prompt if secrets are found |
| Pre-tool use | Scans commands, file reads, and MCP calls before the AI executes them | Blocks the action if secrets are found |
| Post-tool use | Scans tool outputs after execution | Sends a desktop notification if secrets are found |
ggshield uses the same detection engine as all other scanning commands, covering 600+ types of secrets.
Prerequisites
ggshieldversion 1.53.0 or later forggshield machine setup(hooks themselves work from 1.49.0, 1.51.0 for Codex, and 1.54.0 for Mistral Vibe)- A GitGuardian API key (see Getting started)
- One of the supported AI coding tools: Cursor, Claude Code, Codex, Copilot CLI, VS Code, or Mistral Vibe
Installation
One command configures the hook for every AI coding tool on your machine:
ggshield machine setup
machine setup detects which agents you have installed and writes the correct hook configuration for each one, registering ggshield on all three hook stages. It skips agents that are not present, so nothing is written for tools you do not use.
The command also installs the git pre-commit and pre-push hooks and plants a honeytoken. To set up the AI hooks alone:
ggshield machine setup --no-git-hooks --no-honeytokens
To target specific assistants, use --agent or --exclude-agent, which accept claude-code, codex, copilot, cursor, vibe, and vscode:
ggshield machine setup --agent cursor --agent claude-code
Where the hooks are written
machine setup writes hooks for the current user, in the following files:
| Tool | Hook configuration |
|---|---|
| Cursor | ~/.cursor/hooks.json |
| Claude Code | ~/.claude/settings.json |
| Codex | ~/.codex/hooks.json |
| Copilot CLI and VS Code | ~/.copilot/hooks/hooks.json |
| Mistral Vibe | ~/.vibe/hooks.toml |
Those are Copilot's own hook files rather than an editor's settings, so a single install covers Copilot wherever it runs: the Copilot CLI in a terminal, VS Code, and any other IDE whose Copilot extension runs the Copilot CLI.
ggshield merges its hooks into an existing configuration without touching other hooks, so machine setup is safe to re-run: it adds what is missing and leaves existing entries alone. It then verifies that it can authenticate to GitGuardian, reports whether the hook is ready to scan, and tells you how to fix it if not. On macOS, this also triggers the system keychain authorization prompt while you can still approve it interactively.
Installing for a single project
To scope hooks to the current repository instead of your whole user account, install per tool with the local mode:
ggshield install -t cursor -m local
Use --force to overwrite ggshield's own hooks, for example if they were customized and you want to reset them.
For GitHub Copilot, a local install writes to .github/hooks/hooks.json in the repository. Prefer the global install: Copilot loads repository hooks only after you confirm folder trust, and skips them in prompt mode (copilot -p) unless you opt in through an environment variable.
ggshield install -t <assistant> is deprecated for global installs as of ggshield 1.53.0. It still works, and it remains the way to install git hooks (-t pre-commit and -t pre-push), but ggshield machine setup is now the recommended way to configure AI hooks.
Mistral Vibe only loads project hooks from folders you have marked as trusted, so a local install there takes effect once the folder is trusted.
What the developer sees
When ggshield detects a secret, the AI coding tool displays a blocking message. For example, in Cursor:
Detected 1 secret
- Google API Key (valid): AIzaSyC****************-*********d5oii7Y
Please remove the secrets from the content before proceeding.
The prompt or action is blocked until the developer removes the secret and retries.
For post-tool-use detections (where the action already ran), ggshield sends a desktop notification alerting the developer.
When ggshield cannot scan
If ggshield cannot scan an interaction — for example because it is not authenticated, the GitGuardian API is unreachable, or its API token cannot be read — it does not block the action. Instead, it allows the interaction and shows a warning in the AI coding tool noting that the content was not scanned for secrets, along with how to fix it.
This fail-open design keeps your AI coding tool usable when ggshield is misconfigured. To restore scanning, follow the remediation in the warning (typically re-authenticating with ggshield auth login), then confirm with ggshield machine doctor, which reports whether each agent's hook is installed and whether your token can reach GitGuardian.
Handling false positives
If ggshield blocks an action on a secret that is a known false positive, you can tell ggshield to ignore it:
ggshield secret ignore --last-found
This adds the detected secret to your .gitguardian.yaml ignore list. Future scans (including AI hook scans) will skip it.
Uninstallation
To remove the hooks, delete the ggshield entries from the tool's configuration file, using the paths listed in Where the hooks are written.
Deploying at fleet scale
The commands above set up hooks on one machine. To push them across every developer workstation through your MDM, without asking each developer to opt in, see Prevent leaks with AI Hooks.
See also
- ggshield secret scan ai-hook reference: CLI reference for the underlying scan command
- Getting started with ggshield: Installation and authentication
