# How the Auto-Update Post-Commit Hook Works in Understand Anything

> Discover how the auto-update post-commit hook in Egonex-AI Understand Anything synchronizes your knowledge graph instantly with zero LLM tokens spent on cosmetic changes when using --auto-update.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-13

---

**When you run `understand --auto-update`, the tool installs a post-commit Git hook that automatically synchronizes your project's knowledge graph through four deterministic phases, spending zero LLM tokens on cosmetic changes.**

The **auto-update post-commit hook** in [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) keeps your knowledge graph continuously synchronized with your repository after every commit. This mechanism is defined in the internal hook prompt file [[`auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/auto-update-prompt.md)](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md) and operates entirely within the `.understand-anything/` directory to minimize overhead.

## The Four-Phase Update Workflow

The hook executes a deterministic pipeline that filters noise, detects structural changes, and updates only what is necessary.

### Phase 0: Pre-Flight Validation

This phase performs zero-cost sanity checks before invoking any LLM resources. According to the prompt file (lines 24-30), the hook:

- Verifies that [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) and [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json) exist in `.understand-anything/`
- Compares the current Git commit hash against the stored hash in [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json); if they match and `--force` is not supplied, the hook exits immediately
- Determines changed files using `git diff <lastCommitHash>..HEAD --name-only`
- Filters results to source-code extensions and applies rules from `.understandignore` (see Step 9 of the prompt)

### Phase 1: Structural Fingerprint Check

To avoid unnecessary LLM calls, the hook employs a **structural fingerprint** mechanism. A temporary Node.js script (`fingerprint-check.mjs`) computes SHA-256 hashes for each changed file and extracts high-level signatures including functions, classes, imports, and exports.

Each file receives a classification:

- **NONE**: No relevant changes
- **COSMETIC**: Formatting or comment changes only
- **STRUCTURAL**: Logic, API, or dependency changes

Based on these classifications (lines 94-121), the hook decides among four actions: `SKIP`, `PARTIAL_UPDATE`, `ARCHITECTURE_UPDATE`, or `FULL_UPDATE`.

### Phase 2: Targeted Re-Analysis

If Phase 1 returns `PARTIAL_UPDATE` or `ARCHITECTURE_UPDATE`, the hook dispatches the `file-analyzer` agent only on the affected files. These files are processed in batches to minimize token usage. The resulting nodes and edges are merged into the existing graph, with stale entries removed and IDs deduplicated.

### Phase 3: Conditional Architecture Update and Persistence

The final phase handles high-level graph architecture and persistence:

- When `ARCHITECTURE_UPDATE` is signaled, the `architecture-analyzer` sub-agent recomputes layer assignments
- Otherwise, a lightweight adjustment places new files in the most likely existing layer and removes deleted files
- A validation pass removes dangling edges and ensures every node belongs to a layer
- Updated data is written to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and [`.understand-anything/meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/meta.json)
- Fingerprints are **patched** rather than overwritten to maintain accuracy for future comparisons (lines 143-186)

## Token-Efficient Design Philosophy

The hook's architecture deliberately **spends zero LLM tokens for cosmetic changes** such as formatting adjustments or simple logic tweaks. Only structural modifications trigger LLM-driven analysis, and even then, the system processes the minimal file set required. This prevents runaway full-graph rebuilds while maintaining synchronization speed.

If the fingerprint check encounters errors, the system falls back to a safe mode that treats all changes as structural (lines 107-110), guaranteeing graph consistency at the cost of additional tokens.

## Installing and Using the Auto-Update Hook

Enable the auto-update feature by running the `understand` command with the `--auto-update` flag:

```bash

# Install the hook and create initial knowledge graph

understand --auto-update

```

After installation, the hook activates automatically on every commit:

```bash

# Make a structural change

git add src/utils.ts
git commit -m "Add new helper function"

```

The hook produces concise console output indicating the action taken:

- "Knowledge graph is already up to date." (cosmetic changes only)
- "Structural change detected: 1 file → PARTIAL_UPDATE" (minor structural edit)
- "Major structural change detected → recommend /understand --full" (large-scale changes)

To bypass the commit hash comparison and force a fresh analysis:

```bash
understand --auto-update --force

```

## Key Implementation Files

The auto-update mechanism relies on several core components:

- **[[`auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/auto-update-prompt.md)](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md)**: Defines the complete four-phase workflow and decision logic
- **[[`ignore-filter.js`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.js)](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/dist/ignore-filter.js)**: Implements `.understandignore` filtering used in Phase 0
- **[[`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts)](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/fingerprint.ts)**: Generates persistent fingerprints stored in [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json)
- **[[`file-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/file-analyzer.md)](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/file-analyzer.md)**: Agent definition for individual file analysis
- **[[`architecture-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/architecture-analyzer.md)](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/architecture-analyzer.md)**: Handles layer recomputation for architectural updates
- **[[`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json)](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/meta.json)**: Stores the last processed commit hash and metadata

Intermediate data during processing lives in `.understand-anything/intermediate/` and is cleaned up automatically at the end of each run (line 192).

## Summary

- The **auto-update post-commit hook** runs four deterministic phases after every Git commit when enabled with `--auto-update`
- **Phase 0** validates file existence and compares commit hashes to prevent redundant processing
- **Phase 1** uses SHA-256 structural fingerprints to classify changes as NONE, COSMETIC, or STRUCTURAL without LLM calls
- **Phase 2** dispatches the `file-analyzer` agent only on structurally changed files, merging results into the existing graph
- **Phase 3** conditionally runs `architecture-analyzer` for layer updates, validates graph integrity, and persists changes to [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) and [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json)
- The system respects `.understandignore` rules and falls back to safe-mode analysis if fingerprint checks fail

## Frequently Asked Questions

### How does the hook determine if a change is cosmetic versus structural?

The hook runs a temporary Node.js script (`fingerprint-check.mjs`) that computes SHA-256 hashes and extracts signatures for functions, classes, imports, and exports. If only comments or formatting changed, the classification is **COSMETIC** and the hook skips LLM analysis. If signatures differ, the change is **STRUCTURAL**, triggering targeted re-analysis.

### What happens if the fingerprint check fails or encounters an error?

According to lines 107-110 of the prompt file, the hook implements a safe fallback that treats all changes as structural. This guarantees knowledge graph consistency by ensuring no changes are missed, though it consumes additional LLM tokens compared to the optimized path.

### Can I force a full re-analysis even if the commit hash hasn't changed?

Yes. Pass the `--force` flag when running the understand command: `understand --auto-update --force`. This bypasses the commit hash comparison in Phase 0, causing the hook to reprocess all files regardless of the stored state in [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json).

### Where does the hook store intermediate data during processing?

All intermediate artifacts are written to `.understand-anything/intermediate/` and automatically cleaned up at the end of the workflow (line 192). The final outputs persist in [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and [`.understand-anything/meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/meta.json), with fingerprints maintained in [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json).