Hooks

Git Workflow ships opt-in hooks for commit review and main-agent completion. Successful git commit and git push commands can provide a bounded diff to the active host for review. A Stop hook can send a local completion notification without re-entering the model.

Host registration

The shared implementation is hooks/review-commit.sh.

Host	Registration	Output
Claude Code	hooks/claude-hooks.json, selected by the Claude manifest	Plain review context with Claude’s asynchronous re-wake behavior
Codex	hooks/hooks.json, discovered by the Codex plugin	Synchronous JSON containing hookSpecificOutput.additionalContext

Both registrations use PostToolUse for commit review and Stop for completion alerts. Claude uses asynchronous re-wake behavior for commit review; Codex runs that path synchronously for compatibility with supported Codex clients. The commit script parses the hook payload and exits without output unless the executed command contains git commit or git push.

Enable it

The hook is disabled by default. Add this project-local file:

.git-workflow/git-workflow.local.md

review-on-commit: true

The neutral path is checked first. For compatibility, the script falls back to .claude/git-workflow.local.md when the canonical file is absent. Restart or reload the host after changing plugin hook registration.

To disable the behavior, set the value to false or remove the opt-in file.

What it does

After an eligible command, the script:

1. Reads the hook JSON from standard input and extracts the Bash command.
2. Verifies that project opt-in is enabled.
3. Resolves the current commit SHA.
4. Checks .git-workflow/.git-workflow-reviewed-shas to avoid reviewing the same SHA twice.
5. Builds a bounded diff for the new commit or push state.
6. Produces the host-specific output format successfully.
7. Records the SHA only after useful review context was delivered, keeping failures retryable.

The reviewed-SHA ledger is local generated state and should be git-ignored. A legacy .claude/.git-workflow-reviewed-shas ledger is read for duplicate suppression, but new entries are written only to .git-workflow/.

Review behavior

The additional context asks the main workflow to inspect the bounded diff and use pr-reviewer for non-trivial changes. The review path may fan out through $review or /review; it must wait for all requested specialist reports and must not modify source files merely to perform a review.

Large diffs are truncated deliberately so a background hook cannot flood the next agent turn. The message identifies truncation and encourages an explicit full review when needed.

Safety properties

• Disabled unless the repository opts in
• Ignores unrelated Bash commands
• Does not execute the detected commit or push command itself
• Does not modify tracked source files
• Suppresses duplicate SHAs, including those present in the legacy ledger
• Reports malformed hook input and missing runtime dependencies as actionable errors; non-Git directories remain no-op paths
• Keeps hook stdout machine-readable under Codex

Manual testing

From a temporary Git repository containing at least one commit:

printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git status"}}' \
  | hooks/review-commit.sh --host codex

printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git commit -m test"}}' \
  | hooks/review-commit.sh --host codex

The first call emits nothing. The second also emits nothing until .git-workflow/git-workflow.local.md enables the feature. With opt-in enabled, Codex output must be valid JSON and include hookSpecificOutput.additionalContext.

Completion alerts are independently disabled until .git-workflow/config.yaml sets notifications.agentComplete: true. They apply only to the main turn; no SubagentStop hook is registered. The adapter stores a bounded deduplication digest rather than the full assistant message. See Notifications for formats, privacy, and troubleshooting.

Run the repository’s automated hook checks with:

bash scripts/test-review-hook.sh

Troubleshooting

Hook never runs

• Confirm the plugin is enabled and start a fresh host session.
• Confirm the host loaded the correct registration file.
• Verify .git-workflow/git-workflow.local.md contains review-on-commit: true.
• Verify the Bash payload actually contains git commit or git push.
• Verify Python 3 is available; the hook uses it for input parsing and Codex JSON output.

Codex reports invalid hook output

Run the script manually and pipe the result through python3 -m json.tool. Diagnostic output must go to stderr; successful Codex context is emitted as one JSON object on stdout.

A commit is skipped

Inspect .git-workflow/.git-workflow-reviewed-shas and the legacy fallback ledger. Removing the current SHA permits a new review, but normally the ledger should be left intact to prevent repetition.

Package root is unresolved

Skill instructions resolve bundled resources from the loaded SKILL.md path. Hook registration is host-specific and still receives its package context from the host. If a hook command cannot resolve its package, reload the installed plugin and inspect the matching registration JSON.