grok-build-upstream-mirror/crates/codegen/xai-grok-hooks/examples/README.md

Hook Examples

Sample hooks for Grok. Copy to ~/.grok/hooks/ to enable globally, or to <project>/.grok/hooks/ for project-scoped hooks (requires /hooks-trust).

Available Examples

1. Safe Shell Guard (safe-shell.json)

Type: blocking (PreToolUse)

Denies obviously destructive shell commands before they execute:

• rm -rf /, sudo rm -rf, mkfs, dd to devices, fork bombs

Install:

mkdir -p ~/.grok/hooks/bin
cp examples/hooks/safe-shell.json ~/.grok/hooks/
cp examples/hooks/bin/safe-shell-guard.sh ~/.grok/hooks/bin/
chmod +x ~/.grok/hooks/bin/safe-shell-guard.sh

2. No Recursive Grep (no-recursive-grep.json)

Type: blocking (PreToolUse)

Denies recursive grep invocations in the shell before they execute:

• grep -r, grep -R, grep --recursive, grep --dereference-recursive, grep -d recurse, clustered flags (grep -rn, grep -nri), and rgrep

Recursive grep walks an entire directory tree into memory and can OOM-kill the agent process on large repos. The system prompt already steers the model away from this, but a prompt is advisory — this hook makes it a hard, deterministic block. Point the model at the dedicated search tool (ripgrep-backed) instead.

It is careful to avoid false positives: ls -R | grep foo (the -R belongs to ls), grep -e -r file (-r is the pattern), and grep -- -r file are all allowed.

Install:

mkdir -p ~/.grok/hooks/bin
cp examples/hooks/no-recursive-grep.json ~/.grok/hooks/
cp examples/hooks/bin/no-recursive-grep-guard.py ~/.grok/hooks/bin/
chmod +x ~/.grok/hooks/bin/no-recursive-grep-guard.py

(Requires python3 on PATH.)

3. Session Audit Log (session-log.json)

Type: passive (SessionStart + SessionEnd)

Appends session metadata to ~/.grok/session-audit.log — event, session ID, cwd, timestamp.

Install:

mkdir -p ~/.grok/hooks/bin
cp examples/hooks/session-log.json ~/.grok/hooks/
cp examples/hooks/bin/session-log.sh ~/.grok/hooks/bin/
chmod +x ~/.grok/hooks/bin/session-log.sh

4. Tool Activity Logger (tool-logger.json)

Type: passive (PreToolUse + PostToolUse)

Logs all tool calls to ~/.grok/tool-activity.log — tool name, event type, effective tool name, backgrounded status.

Install:

mkdir -p ~/.grok/hooks/bin
cp examples/hooks/tool-logger.json ~/.grok/hooks/
cp examples/hooks/bin/tool-logger.sh ~/.grok/hooks/bin/
chmod +x ~/.grok/hooks/bin/tool-logger.sh

Format

Hook files use the Claude-compatible JSON format:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bin/check.sh", "timeout": 5 }
        ]
      }
    ]
  }
}

• Event names: SessionStart, PreToolUse, PostToolUse, SessionEnd
• Matcher: regex on tool name. Claude names like Bash, Read, Edit are auto-expanded to also match Grok names (run_terminal_cmd, read_file, search_replace)
• Timeout: in seconds (default: 5)
• Command: path to script (relative to hook file directory) or inline shell command

Script Contract

Scripts receive the hook event envelope as JSON on stdin and should write a response to stdout:

For blocking hooks (PreToolUse):

{"decision":"allow"}

or

{"decision":"deny","reason":"Explanation for the user"}

Exit codes: 0 = allow, 2 = deny, other = fail-open.

For passive hooks: stdout is informational only. Exit 0 for success.

Uninstall

Remove the JSON file from ~/.grok/hooks/. The hook stops running on the next session.