How the `--auto-update` Post‑Commit Hook Automatically Patches Knowledge Graphs on Every Git Commit

The --auto-update post-commit hook runs a deterministic four-phase pipeline after every git commit to incrementally patch the knowledge graph, consuming LLM tokens only when structural code changes are detected.

The Egonex-AI/Understand-Anything repository provides an --auto-update flag that installs a Git post-commit hook to keep your knowledge graph synchronized with code changes. When enabled, this hook executes the multi-phase pipeline defined in understand-anything-plugin/hooks/auto-update-prompt.md, ensuring that every commit has a matching graph snapshot without requiring a full repository re-analysis.

Architectural Overview of the Auto-Update Pipeline

The auto-update mechanism operates through four distinct phases designed to minimize computational overhead while maintaining graph accuracy. As implemented in understand-anything-plugin/hooks/auto-update-prompt.md, the pipeline processes each commit deterministically, from initial validation through final persistence.

Phase 0: Pre-Flight Validation

The hook begins by verifying that a valid graph exists and checking whether work is actually required. It confirms the presence of .understand-anything/knowledge-graph.json and meta.json, then compares the current HEAD hash against the stored commit hash in meta.json. If the hashes match, the pipeline aborts immediately, consuming zero tokens. The phase also generates a list of changed source files using git diff and applies .understandignore rules via ignore-filter.js to exclude migrations, vendored code, or test files.

Phase 1: Structural Fingerprint Check

This phase determines whether changes are cosmetic or structural by analyzing file fingerprints. A Node.js script loads fingerprints.json and computes SHA-256 hashes for each changed file, classifying them as NONE, COSMETIC, or STRUCTURAL based on public API signatures extracted via regex. The system then decides the update scope: SKIP, PARTIAL_UPDATE, ARCHITECTURE_UPDATE, or FULL_UPDATE. This classification operates entirely locally without LLM token consumption, leveraging the fingerprinting logic defined in understand-anything-plugin/packages/core/dist/fingerprint.ts.

Phase 2: Targeted Re-Analysis

When structural changes are detected, the hook dispatches the file-analyzer agent—defined in understand-anything-plugin/agents/file-analyzer.md—only on the affected files, batching requests to process a maximum of ten files per LLM call. This targeted approach generates fresh GraphNode and GraphEdge objects exclusively for modified code, avoiding the cost of re-analyzing unchanged portions of the codebase.

Phase 3: Merge and Save

The final phase integrates new analysis results into the existing graph. The hook removes stale nodes and edges belonging to re-analyzed files, inserts the fresh results, and optionally triggers the architecture-analyzer agent—specified in understand-anything-plugin/agents/architecture-analyzer.md—if the update scope requires architectural recomputation. It then persists the updated graph to .understand-anything/knowledge-graph.json, refreshes meta.json with the new commit hash, and patches fingerprints.json using a load-patch-save strategy to prevent cascade FULL_UPDATE bugs.

Error Handling and Fallbacks

The pipeline includes robust error recovery mechanisms. If fingerprinting fails, the system falls back to a FULL_UPDATE to ensure graph integrity. Sub-agent dispatch operations retry once before failing, and the system always preserves partial results to prevent data loss during interrupted updates.

Hook Installation and Wiring

The post-commit hook is registered in understand-anything-plugin/hooks/hooks.json and installed when users run the /understand --auto-update command. The CLI writes a Git hook script that invokes the auto-update prompt, passing critical environment variables including $PROJECT_ROOT (the repository root) and $PLUGIN_ROOT (the installed plugin location) to locate supporting utilities.

{
  "name": "post-commit",
  "script": "node $PROJECT_ROOT/.understand-anything/hooks/auto-update.mjs"
}

The hook script loads the markdown specification from understand-anything-plugin/hooks/auto-update-prompt.md, parses the defined phases, and orchestrates the execution using Node.js utilities located in the plugin directory.

Token Efficiency and Performance Optimization

Zero-Token Fast Path

Most commits involve cosmetic changes such as formatting or comment updates. The pre-flight and fingerprint phases run entirely locally, consuming no LLM tokens for these common scenarios. Only commits that modify public APIs—new or removed functions, classes, imports, or exports—trigger token-consuming analysis.

Incremental Graph Merging

By patching only the affected portions of fingerprints.json and updating specific nodes in knowledge-graph.json, the system prevents the "all files look new" bug that previously caused perpetual FULL_UPDATE loops (see issue #152). This incremental approach ensures that unchanged file fingerprints persist across commits, maintaining stable identifiers for the dependency graph.

Practical Usage Examples

Enabling Auto-Update

Install the post-commit hook and enable automatic graph patching with a single command:

# Install the hook and turn on auto-update

understand --auto-update

This command configures Git to trigger the knowledge graph update pipeline after every commit.

Internal Pipeline Execution

The hook executes the following simplified workflow internally:

# Phase 0 – Detect changed files and verify state

git rev-parse HEAD
git diff <lastCommitHash>..HEAD --name-only | grep -E '\.(ts|tsx|js|jsx|py|go|rs|java|rb|cpp|c|h|cs|swift|kt|php)$'

# Phase 1 – Check fingerprints for structural changes

node .understand-anything/intermediate/fingerprint-check.mjs

# Phase 2 – Re-analyze changed files (example batch)

understand --skill file-analyzer src/new-feature.ts src/utils.ts

# Phase 3 – Merge results back into knowledge-graph.json

# (Handled automatically by the hook's merge logic)

Fingerprint Patching Strategy

The final step loads the entire fingerprints.json, patches only the entries for files that changed, and writes the complete set back to disk. This approach prevents the cascade FULL_UPDATE bug by ensuring that unchanged files retain their existing fingerprints, avoiding the scenario where the system treats all files as new on subsequent commits.

Summary

• The --auto-update post-commit hook triggers a four-phase pipeline after every git commit to maintain synchronization between code and knowledge graph.
• Phase 0 validates existing state and detects changed files, while Phase 1 uses SHA-256 fingerprinting to classify changes as cosmetic or structural without consuming LLM tokens.
• Phase 2 dispatches the file-analyzer agent only on structurally changed files (batched ≤10 per request), and Phase 3 merges results into .understand-anything/knowledge-graph.json.
• The hook is wired through understand-anything-plugin/hooks/hooks.json and respects .understandignore rules to filter irrelevant files.
• Robust error handling includes fallback to FULL_UPDATE and retry logic for sub-agent dispatch, ensuring graph integrity even when fingerprinting fails.

Frequently Asked Questions

What triggers a FULL_UPDATE versus a PARTIAL_UPDATE?

A FULL_UPDATE occurs when the fingerprinting mechanism fails or when structural changes affect the global architecture of the codebase, requiring the architecture-analyzer agent to recompute high-level relationships. A PARTIAL_UPDATE handles localized changes to specific files where only the file-analyzer needs to regenerate nodes and edges for the affected modules, as determined by the classification logic in Phase 1.

How does the hook handle cosmetic changes like formatting or comments?

Cosmetic changes are classified as COSMETIC during Phase 1's fingerprint check, which computes SHA-256 hashes and extracts public API signatures using regex patterns. Since these changes don't alter function signatures, class definitions, or imports, the pipeline skips LLM analysis entirely, consuming zero tokens and leaving the knowledge graph unchanged while updating file hashes in fingerprints.json.

Where does the hook store the fingerprints and graph state?

The hook maintains state in three primary files within the .understand-anything directory: knowledge-graph.json stores the graph structure, meta.json tracks the last processed commit hash, and fingerprints.json contains the SHA-256 hashes used for structural change detection. These files are updated atomically during Phase 3 to ensure consistency across the pipeline.

Can I exclude specific files from triggering graph updates?

Yes, the hook respects .understandignore rules during Phase 0 to filter out migrations, vendored dependencies, test files, and other non-production code. By adding patterns to your .understandignore file, you prevent unnecessary structural analysis and token consumption for files that don't contribute to your core knowledge graph, as enforced by the ignore-filter.js utility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}