How the `--auto-update` Flag Enables Post-Commit Hook Graph Updates in Understand-Anything

The --auto-update flag persists a configuration setting to .understand-anything/config.json that activates a Git post-commit hook, triggering incremental knowledge graph updates automatically after every commit.

The Egonex-AI/Understand-Anything repository provides a code analysis skill that maintains a structured knowledge graph of your codebase. By enabling the --auto-update flag, developers automate the synchronization between code changes and graph updates without manual intervention.

Enabling Persistent Auto-Update Configuration

When you invoke the /understand skill with the --auto-update flag, the system writes a JSON configuration object to .understand-anything/config.json. According to the skill definition in understand-anything-plugin/skills/understand/SKILL.md (lines 13-16), this flag sets the autoUpdate property to true within the ProjectConfig interface defined in understand-anything-plugin/packages/core/src/types.ts.

To enable automatic updates, run:

/understand --auto-update

This creates the following configuration structure:

{
  "autoUpdate": true
}

Post-Commit Hook Activation Logic

The Git hook responsible for triggering updates is defined in understand-anything-plugin/hooks/hooks.json (lines 9-19). As implemented in Egonex-AI/Understand-Anything, this hook executes after Git commit, merge, cherry-pick, or rebase operations.

The hook validates two critical conditions before proceeding:

• The repository contains .understand-anything/config.json with "autoUpdate": true.
• The knowledge graph files (knowledge-graph.json, meta.json) exist from a previous analysis.

When both conditions pass, the hook emits a message instructing Claude Code (or compatible LLM environments) to execute the instructions in understand-anything-plugin/hooks/auto-update-prompt.md.

Hook Implementation Details

The post-commit hook uses a shell command to detect Git operations and verify configuration state:

{
  "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.\""
}

Incremental Graph Update Execution

The auto-update-prompt.md file implements the incremental graph-update workflow. This process minimizes computational overhead by analyzing only changed files rather than the entire codebase.

Changed File Detection

The workflow loads the previously generated structural fingerprints (baseline) and detects changes by comparing the current HEAD against the last analyzed commit hash stored in meta.json:

git diff $(cat .understand-anything/meta.json | jq -r .gitCommitHash) HEAD --name-only > changed-files.txt

Selective Batch Recomputation

Rather than rebuilding the entire graph, the system recomputes only the batches containing modified files:

node compute-batches.mjs $PROJECT_ROOT \
  --changed-files=$PROJECT_ROOT/.understand-anything/tmp/changed-files.txt

Graph Merging and State Persistence

After re-analyzing the changed batches, the system merges new results with the existing graph, removes obsolete nodes and edges for changed files, and regenerates the fingerprint baseline. Finally, it updates meta.json with the new commit hash:

# Merge new batch results with existing graph

python merge-batch-graphs.py $PROJECT_ROOT

# Regenerate fingerprints and update metadata for next comparison

node build-fingerprints.mjs $PROJECT_ROOT/.understand-anything/intermediate/fingerprint-input.json

Disabling Automatic Updates

To deactivate the post-commit hook automation, run the skill with the --no-auto-update flag. This writes {"autoUpdate": false} to .understand-anything/config.json, causing the hook's verification check to fail silently on subsequent commits without triggering graph updates.

Summary

• The --auto-update flag writes {"autoUpdate": true} to .understand-anything/config.json, utilizing the ProjectConfig interface from understand-anything-plugin/packages/core/src/types.ts.
• The post-commit hook defined in understand-anything-plugin/hooks/hooks.json monitors Git operations and validates that auto-update is enabled and graph files exist before triggering updates.
• The incremental workflow in understand-anything-plugin/hooks/auto-update-prompt.md performs targeted analysis of changed files using git diff, merges results with the existing graph, and updates structural fingerprints and metadata.
• Use --no-auto-update to disable the feature and prevent automatic graph regeneration after commits.

Frequently Asked Questions

Where does the --auto-update flag store its configuration?

The flag writes to .understand-anything/config.json in the project root, setting the autoUpdate property to true according to the skill definition in understand-anything-plugin/skills/understand/SKILL.md. The hook checks this file to determine whether to trigger incremental updates.

What Git operations trigger the auto-update hook?

According to understand-anything-plugin/hooks/hooks.json, the hook responds to commit, merge, cherry-pick, and rebase operations. Any of these commands initiates the graph update workflow if auto-update is enabled and knowledge graph files exist.

How does the system avoid re-analyzing the entire codebase?

The incremental workflow uses git diff against the commit hash stored in meta.json to identify changed files. It then recomputes only the affected batches, merges the new results with the existing knowledge-graph.json, and prunes obsolete nodes rather than performing a full rebuild.

Can I disable auto-update after enabling it?

Yes. Run /understand --no-auto-update to write {"autoUpdate": false} to the configuration file. The post-commit hook checks this value during its validation phase and skips the update process when the flag is disabled.

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