Git Hooks & Session Management

Relevant source files

The following files were used as context for generating this wiki page:

• hooks/session-start.sh
• hooks/hooks.json
• code_review_graph/skills.py
• code_review_graph/main.py
• code-review-graph-vscode/src/extension.ts
• CLAUDE.md

Git Hooks and Session Management constitute the automation layer of the code-review-graph project, ensuring that the structural knowledge graph remains synchronized with the source code during development workflows. This system automatically triggers graph updates upon file changes and git commits, while providing status feedback when a developer starts a new session in an AI coding environment.

The system integrates across multiple platforms, including CLI, VS Code, and various AI agents like Claude Code, Cursor, and Gemini CLI. By utilizing native Git hooks and platform-specific session events, it minimizes the need for manual indexing, facilitating a "local-first" incremental update experience.

Sources: CLAUDE.md:1-15, code_review_graph/skills.py:25-35

Git Hooks Architecture

The project implements Git hooks to perform risk analysis and graph synchronization during the standard Git workflow. The primary implementation is a pre-commit hook that intercepts commit attempts to provide immediate feedback on code changes.

Pre-Commit Integration

The install_git_hook function resolves the correct hooks directory using git rev-parse --git-path hooks to support linked worktrees and submodules. It installs a shell script that executes update and detect-changes --brief before a commit is finalized.

The logic ensures that the knowledge graph is current before the developer commits, providing a risk-scored impact analysis of the changes.

Sources: code_review_graph/skills.py:641-685, code_review_graph/main.py:465-490

Session & Tool Lifecycle Hooks

Beyond standard Git hooks, the project configures "AI Agent Hooks" that trigger based on the lifecycle of a development session or the use of editing tools. These are configured through settings.json or mcp.json files depending on the platform.

Lifecycle Events

Event Name	Trigger Condition	Primary Action
SessionStart	Opening a project or starting a CLI agent session	Runs status to report graph health
PostToolUse	After an AI agent uses Write, Edit, or Bash tools	Runs update --skip-flows for fast sync
AfterTool	Specific to Gemini CLI; triggers after file replacement	Executes crg-update.sh

Sources: code_review_graph/skills.py:541-575, code_review_graph/skills.py:781-810

Automated Update Flow

When a developer saves a file or an AI agent modifies code, the system initiates a debounced update. In VS Code, this is managed via a FileSystemWatcher and an onDidChange event, which re-initializes the SqliteReader to pick up external writes.

Platform Specific Implementations

The implementation of session management varies significantly across supported platforms to leverage native capabilities.

VS Code Extension

The VS Code extension manages lifecycle through activate and deactivate functions. It sets up a FileSystemWatcher specifically for .code-review-graph/graph.db to ensure the UI remains consistent with the background database.
Sources: code-review-graph-vscode/src/extension.ts:498-540

Gemini CLI

Gemini CLI uses specialized shell scripts located in .gemini/hooks/.

• crg-session-start.sh: Drains stdin and outputs a JSON object containing the system message from code-review-graph status.
• crg-update.sh: Performs an incremental update and returns {"suppressOutput": true} to keep the session log clean.
  Sources: code_review_graph/skills.py:733-775, hooks/session-start.sh:1-12

Cursor & OpenCode

• Cursor: Uses a hooks.json (version 1) to map afterFileEdit, sessionStart, and beforeShellExecution to local shell scripts.
• OpenCode: Implements a TypeScript plugin (crg-plugin.ts) using Bun's shell API to listen for file.edited and session.created events.
  Sources: code_review_graph/skills.py:840-865, code_review_graph/skills.py:975-1025

Configuration and Metadata

Session and hook behaviors are governed by environment variables and local configuration files.

Environment Variable	Description
CRG_RECURSE_SUBMODULES	Determines if hooks should process submodules.
CRG_TOOL_TIMEOUT	Maximum execution time for hook-triggered tools.
CRG_TOOLS	Allow-list of tools available to the session.

The hooks.json file provides the template for standard tool-use interceptions:

{
  "PostToolUse": [
    {
      "matcher": "Write|Edit|Bash",
      "hooks": [
        {
          "type": "command",
          "command": "cat >/dev/null || true; code-review-graph update --skip-flows",
          "timeout": 30
        }
      ]
    }
  ]
}

Sources: hooks/hooks.json:1-15, code_review_graph/main.py:100-115, code_review_graph/main.py:650-660

Conclusion

Git Hooks and Session Management provide the necessary automation to maintain a high-fidelity knowledge graph without manual developer intervention. By hooking into both low-level Git events and high-level AI agent lifecycles, the project ensures that code analysis is always based on the most recent state of the repository, significantly reducing token consumption by providing precise, incremental context.

Sources: CLAUDE.md:145-160, code_review_graph/skills.py:1050-1060