Skip to main content
Claude Code hooks let you insert deterministic checks into the agent loop. This pattern is not a Git hook. It is a local PreToolUse gate on Claude’s Bash tool. When Claude tries git commit or git push, the hook runs fallow audit --format json --quiet --explain. pass and warn are allowed. fail is blocked, and the JSON findings are sent back to Claude on stderr so it can fix the code and retry.
This is Option C: local agent gate in the adoption rollout. Use it together with the shared CI gate from fallow audit, not instead of it. See Adopt Fallow in an existing repo.

​
Install it in one command

fallow setup-hooks
That command writes a project-level .claude/settings.json and .claude/hooks/fallow-gate.sh. It detects whether your repo also has an AGENTS.md or .codex/ and, if so, adds a managed Codex fallback block to AGENTS.md as well. To remove the generated artifacts later, run fallow setup-hooks --uninstall. Preview first with --dry-run: 
fallow setup-hooks --dry-run
Output looks like this, with one line per affected path and a description of what changed: 
fallow setup-hooks (install):
  .claude/settings.json          updated (1 handler added, 1 preserved)
  .claude/hooks/fallow-gate.sh   created
  AGENTS.md                      managed block inserted

​
Install globally for every repo

Pass --user to install the gate under your home directory instead of per-project. The settings file lands at ~/.claude/settings.json, the hook script at ~/.claude/hooks/fallow-gate.sh, and the emitted handler command uses "$HOME" in place of "$CLAUDE_PROJECT_DIR" so it resolves in every repo Claude Code opens: 
fallow setup-hooks --user
Project-level installs override the global one when both are present, so you can still opt a specific repo into a stricter or laxer policy.

​
Remove it

fallow setup-hooks --uninstall
Removes the fallow-gate handler from .claude/settings.json, deletes the hook script if it still carries the generator marker (use --force to remove user-edited scripts), and strips the managed block from AGENTS.md. Handlers you added outside fallow stay untouched. Pass --user to uninstall the global artifacts at ~/.claude/ instead of the project ones. The uninstall flow is idempotent: running it a second time prints unchanged / not present and exits 0. Dry-run is supported (--uninstall --dry-run). fallow setup-hooks also recognises and cleans up hook commands that older manual setups emitted (absolute paths, ~/-based paths, Windows drive paths), so re-running it on a pre-existing install upgrades the handler to the canonical form without leaving duplicates.
Related but distinct: fallow init --hooks scaffolds a shell-level Git pre-commit hook in .git/hooks/ that runs fallow on changed files. That is the human enforcement path. This page is the agent enforcement path. The two can be used together: git hooks catch human commits, the setup-hooks gate catches agent commits.

​
Manual setup

​
1. Create .claude/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fallow-gate.sh"
          }
        ]
      }
    ]
  }
}

​
2. Create .claude/hooks/fallow-gate.sh

#!/usr/bin/env bash
set -euo pipefail

# Generated by fallow setup-hooks.
# Requires bash and jq. On Windows run via git-bash or WSL.
# Blocks Claude Code git commit and git push when fallow audit returns verdict fail.
# Runtime errors fail open with a single stderr notice so skips stay visible.

if ! command -v jq >/dev/null 2>&1; then
  echo "fallow-gate: jq not on PATH, skipping audit." >&2
  exit 0
fi

INPUT="$(cat)"
CMD="$(jq -r '.tool_input.command // empty' <<<"$INPUT")"

if ! printf '%s\n' "$CMD" | grep -Eq '(^|[[:space:];|&()])git[[:space:]]+(commit|push)([[:space:]]|$)'; then
  exit 0
fi

if command -v fallow >/dev/null 2>&1; then
  RUNNER=(fallow)
elif command -v npx >/dev/null 2>&1 && VER="$(npx --no-install fallow --version 2>/dev/null || true)" && [[ "$VER" == fallow* ]]; then
  RUNNER=(npx --no-install fallow)
else
  echo "fallow-gate: fallow binary not found (tried PATH and npx --no-install), skipping audit." >&2
  exit 0
fi

TMP_JSON="$(mktemp)"
TMP_ERR="$(mktemp)"
cleanup() {
  rm -f "$TMP_JSON" "$TMP_ERR"
}
trap cleanup EXIT

if "${RUNNER[@]}" audit --format json --quiet --explain >"$TMP_JSON" 2>"$TMP_ERR"; then
  STATUS=0
else
  STATUS=$?
fi

VERDICT="$(jq -r '.verdict // empty' <"$TMP_JSON" 2>/dev/null || true)"
IS_ERROR="$(jq -r '.error // false' <"$TMP_JSON" 2>/dev/null || echo false)"

if [ "$VERDICT" = "fail" ]; then
  cat "$TMP_JSON" >&2
  exit 2
fi

if [ "$STATUS" -eq 2 ] || [ "$IS_ERROR" = "true" ]; then
  MSG="$(jq -r '.message // empty' <"$TMP_JSON" 2>/dev/null || true)"
  if [ -n "$MSG" ]; then
    echo "fallow-gate: fallow audit runtime error ($MSG), skipping." >&2
  else
    echo "fallow-gate: fallow audit runtime error, skipping." >&2
  fi
  exit 0
fi

if [ "$STATUS" -ne 0 ]; then
  ERR_LINE="$(sed -n '1p' "$TMP_ERR" 2>/dev/null || true)"
  if [ -n "$ERR_LINE" ]; then
    echo "fallow-gate: fallow audit exited $STATUS ($ERR_LINE), skipping." >&2
  else
    echo "fallow-gate: fallow audit exited $STATUS, skipping." >&2
  fi
  exit 0
fi

exit 0

​
3. Make the script executable

chmod +x .claude/hooks/fallow-gate.sh
The hook checks fallow first, then falls back to npx --no-install fallow. Keep jq on PATH because the hook reads Claude’s stdin JSON and Fallow’s JSON output. Skip paths print one stderr line so the agent does not silently trust a missing gate.
Runtime errors fail open on purpose. In JSON mode, fallow audit reports invalid refs, non-Git directories, and config errors as { "error": true, ... } with exit code 2. Letting those cases through prevents a brand-new repo or empty history from getting stuck before the first successful audit.
This gate runs before Claude executes the shell command, so git push --no-verify does not bypass it. Keep CI on fallow audit as the shared gate for humans and non-Claude workflows.

​
Codex fallback

Codex now has an experimental hooks surface, but the low-friction fallback while it stabilizes is still AGENTS.md. Add this to your repo root AGENTS.md: 
## Fallow local gate

Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
fallow setup-hooks maintains this block for you, scoped between <!-- fallow:setup-hooks:start --> and <!-- fallow:setup-hooks:end --> markers so re-running the command is idempotent.

​
Why this works well with agents

fallow audit --explain gives Claude structured findings with docs links and fix guidance, while Agent Skills teaches the agent how to act on them. The result is a tight feedback loop: Claude tries to commit or push, the gate blocks only real fail-severity issues, Claude reads the JSON envelope, fixes the code, and retries.

Adoption rollout

See Option C: local agent gate next to warn-everywhere and error-plus-baselines.

fallow audit

Reference for verdicts, JSON output, and baselines.

Agent Skills

Teach the agent what to do after the gate blocks.