How the `--auto-update` Command Enables Post-Commit Hooks for Incremental Graph Patching in Understand-Anything

The --auto-update flag writes a persistent configuration that activates a post-commit hook, which automatically triggers deterministic structural fingerprinting to patch the knowledge graph incrementally after every Git commit.

The --auto-update command in the Understand-Anything toolchain eliminates manual graph regeneration by bridging Git operations with automated incremental updates. When enabled, this feature persists project settings to .understand-anything/config.json and leverages a shell-based post-commit hook to detect repository changes and invoke LLM-driven graph patching without requiring full re-analysis.

How the --auto-update Flag Configures Automatic Updates

Persisting Configuration to config.json

When you append --auto-update to the understand CLI command, the system writes a project-level configuration file that enables the hook mechanism. According to the skill definition in understand-anything-plugin/skills/understand/SKILL.md, the flag specifically writes autoUpdate: true to .understand-anything/config.json:

-- `--auto-update` — Enable automatic graph updates on commit (writes `autoUpdate: true` to `.understand-anything/config.json`)
-- `--no-auto-update` — Disable automatic graph updates (writes `autoUpdate: false` to `.understand-anything/config.json`)

This JSON file serves as the persistent state that the post-commit hook checks before triggering any graph updates.

Default Configuration Behavior

By default, the feature remains disabled to prevent unnecessary processing. The default configuration is defined in packages/core/src/persistence/index.ts as:

const DEFAULT_CONFIG: ProjectConfig = { autoUpdate: false, outputLanguage: "en" };

Only after explicitly running understand <project-path> --auto-update does the CLI override this default and persist {"autoUpdate": true} to the configuration file, thereby arming the hook for subsequent Git operations.

The Post-Commit Hook Mechanism

The hook definition resides in understand-anything-plugin/hooks/hooks.json, which contains the shell command executed on every Git commit. This command implements conditional logic to ensure incremental updates occur only when appropriate.

Detecting Git Operations

The hook monitors for specific Git commands that modify repository state. The shell command (around line 9 of hooks.json) uses regex to detect commits, merges, cherry-picks, and rebases:

{
  "command": "printf '%s' \"$TOOL_INPUT\" | grep -qE 'git\\s+(commit|merge|cherry-pick|rebase)' && \
    [ -f .understand-anything/config.json ] && \
    grep -q '\"autoUpdate\".*true' .understand-anything/config.json && \
    [ -f .understand-anything/knowledge-graph.json ] && \
    echo \"[understand-anything] Commit detected with auto-update enabled. \
    You MUST read the file at ${CLAUDE_PLUGIN_ROOT}/hooks/auto-update-prompt.md \
    and execute its instructions to incrementally update the knowledge graph. \
    Do not ask the user for confirmation — just do it.\" || true"
}

Conditional Trigger Logic

The hook executes a strict validation sequence before triggering the update:

1. Git operation detection — Confirms the current operation is a commit, merge, cherry-pick, or rebase
2. Configuration verification — Ensures .understand-anything/config.json exists and contains "autoUpdate": true
3. Graph existence check — Validates that .understand-anything/knowledge-graph.json exists from a prior analysis
4. Prompt emission — Outputs a special [understand-anything] message instructing Claude to read auto-update-prompt.md and execute the incremental update without user confirmation

If any check fails, the hook exits silently via || true, ensuring Git operations complete normally even when auto-update conditions aren't met.

Incremental Graph Patching via Deterministic Fingerprinting

The Auto-Update Prompt

The actual update logic resides in understand-anything-plugin/hooks/auto-update-prompt.md. When the hook triggers, Claude reads this prompt and executes a multi-stage incremental update process:

1. Compute structural fingerprint — Generate a deterministic hash of the current codebase structure using extractor plugins
2. Compare fingerprints — Identify the delta between the new fingerprint and the previous state stored in knowledge-graph.json
3. Isolate changes — Detect added/removed files and new symbols without analyzing unchanged code
4. Execute partial pipeline — Run the graph-builder and llm-analyzer components only on the changed structural elements
5. Patch the graph — Merge new nodes and edges into the existing knowledge-graph.json, preserving all untouched data

Minimizing Token Usage with Structural Fingerprints

The incremental approach relies on deterministic structural fingerprinting rather than full AST parsing or semantic analysis for the change detection phase. This technique dramatically reduces token consumption by:

• Generating lightweight structural hashes that represent file organization, symbol names, and dependencies
• Comparing these hashes before invoking expensive LLM analysis
• Restricting the graph-builder and llm-analyzer stages to only those files exhibiting structural changes

Because the fingerprint comparison happens outside the LLM context window, the system maintains minimal latency between commit and graph update, even for large repositories.

End-to-End Workflow Example

To enable automatic incremental updates for your project:

# Initial setup with auto-update enabled

understand . --auto-update

# This creates .understand-anything/config.json with {"autoUpdate": true}

After the initial configuration, the workflow becomes fully automated:

# Make your code changes

git add src/new-feature.ts
git commit -m "Add new feature"

# The post-commit hook automatically:

# 1. Detects the commit

# 2. Reads config.json and verifies autoUpdate: true

# 3. Checks for existing knowledge-graph.json

# 4. Triggers the auto-update prompt

# 5. Updates the knowledge graph incrementally

The resulting knowledge-graph.json now reflects your latest commit without requiring a manual understand command or full repository re-analysis.

Summary

• The --auto-update flag writes {"autoUpdate": true} to .understand-anything/config.json, enabling the post-commit hook mechanism defined in understand-anything-plugin/hooks/hooks.json.
• The hook validates Git operations, configuration state, and existing graph files before triggering updates via the auto-update-prompt.md instructions.
• Incremental patching uses deterministic structural fingerprinting to identify changes and minimize token usage by running the analysis pipeline only on modified code.
• Default configuration in packages/core/src/persistence/index.ts sets autoUpdate: false, requiring explicit opt-in.
• The system maintains graph synchronization automatically after each commit, merge, cherry-pick, or rebase without manual intervention or full rebuilds.

Frequently Asked Questions

What happens if I commit without an existing knowledge-graph.json?

The post-commit hook checks for the existence of .understand-anything/knowledge-graph.json before triggering the auto-update prompt. If the file is missing, the hook exits silently (via || true), and the commit completes normally without attempting an incremental update. You must run the initial understand command to generate the base graph before --auto-update can function.

Does the auto-update feature work with merge commits and rebases?

Yes. The hook regex in understand-anything-plugin/hooks/hooks.json specifically matches git\s+(commit|merge|cherry-pick|rebase), enabling incremental graph patching for all common Git operations that modify repository state. The system treats these operations identically to standard commits once the structural fingerprint comparison identifies the resulting changes.

How does the system prevent excessive LLM token consumption during auto-updates?

The auto-update prompt in understand-anything-plugin/hooks/auto-update-prompt.md mandates deterministic structural fingerprinting as a prerequisite step. This fingerprinting generates lightweight hashes of code structure without invoking LLM analysis, allowing the system to compare repository states and identify changes cheaply. Only files with structural deltas are passed to the graph-builder and llm-analyzer stages, keeping token usage proportional to the size of the change rather than the entire codebase.

Can I disable auto-update after enabling it?

Yes. Running understand <project-path> --no-auto-update writes {"autoUpdate": false} to .understand-anything/config.json, which causes the post-commit hook to skip the incremental update logic on subsequent commits. The hook will continue to execute but will fail the grep -q '\"autoUpdate\".*true' check, effectively disabling automatic graph patching while preserving your configuration file.

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