How to Enable Auto-Update on Git Commits with `--auto-Update` in Understand Anything

Run understand --auto-update to persist "autoUpdate": true to .understand-anything/config.json, which triggers a post-commit hook that automatically patches the knowledge graph after every git commit.

The Understand Anything tool keeps your knowledge graph synchronized with code changes by watching for git commits. When you enable auto-update, the system writes a configuration flag and installs a hook that executes an incremental update prompt without manual intervention. This ensures each commit is immediately reflected in the graph, eliminating the need to re-run the full /understand command after every change.

How Auto-Update Works

The auto-update mechanism relies on three components: a command-line flag that persists settings, a post-commit hook that detects git activity, and a deterministic prompt that patches the graph incrementally.

The Flag and Configuration

When you append --auto-update to the /understand skill, the CLI parses the argument and calls the persistence layer defined in understand-anything-plugin/skills/understand/SKILL.md. According to the source, lines 15-18 define the flag description, while lines 137-138 implement the logic that writes the setting to disk.

The configuration is stored in packages/core/src/persistence/index.ts, which defines the default value (autoUpdate: false) and merges user overrides. This file ensures the .understand-anything/config.json file is created or updated with the new boolean value.

The Post-Commit Hook Detection

The repository ships with a hook definition in understand-anything-plugin/hooks/hooks.json (lines 9-12) that intercepts git operations. The hook checks three conditions before triggering an update:

1. The command is a git commit, merge, cherry-pick, or rebase
2. .understand-anything/config.json exists and contains "autoUpdate": true
3. A knowledge graph file (knowledge-graph.json) is present in the project directory

If all conditions are met, the hook instructs Claude Code to read hooks/auto-update-prompt.md and execute the instructions immediately.

Incremental Graph Updates

The auto-update-prompt.md file contains deterministic fingerprinting logic that minimizes token usage by updating only changed portions of the graph. This prompt runs automatically in the background; the user does not see the prompt text or need to confirm the action. After execution, the knowledge graph reflects the latest code state, and subsequent /understand runs start from the fresh graph without re-scanning the entire project.

Enabling and Disabling Auto-Update

Enable Auto-Update

Run the skill with the flag to create or update the configuration file:

understand --auto-update

This command writes the following JSON to .understand-anything/config.json:

{
  "autoUpdate": true,
  "outputLanguage": "en"
}

Disable Auto-Update

To turn off automatic synchronization, use the negation flag:

understand --no-auto-update

This updates the configuration to:

{
  "autoUpdate": false,
  "outputLanguage": "en"
}

Verify the Setting

Check your current configuration with:

cat .understand-anything/config.json

The output should display "autoUpdate":true when the feature is active.

Technical Implementation Details

Configuration Persistence

The packages/core/src/persistence/index.ts file handles the default configuration structure and merge logic. It ensures that enabling auto-update does not overwrite other settings like outputLanguage. The persistence layer creates the .understand-anything directory if it does not exist and validates JSON before writing.

Hook Detection Logic

The post-commit hook uses a shell command that pipes TOOL_INPUT through grep to detect git operations. As implemented in understand-anything-plugin/hooks/hooks.json, the logic appears as:

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

This command ensures the auto-update prompt only runs when the repository is properly configured and a graph exists to update.

Summary

• Enable auto-update by running understand --auto-update to write "autoUpdate": true to .understand-anything/config.json
• Post-commit hook in understand-anything-plugin/hooks/hooks.json monitors for git commits, merges, cherry-picks, and rebases
• Incremental updates use hooks/auto-update-prompt.md to patch only changed graph elements, minimizing token usage
• Zero user intervention is required after enabling; the hook executes automatically when conditions are met
• Persistence layer in packages/core/src/persistence/index.ts manages configuration defaults and file I/O

Frequently Asked Questions

Does auto-update work with merge commits and rebases?

Yes. According to the hook definition in understand-anything-plugin/hooks/hooks.json, the detection pattern matches git commit, git merge, git cherry-pick, and git rebase commands. Any of these operations will trigger the incremental graph update if auto-update is enabled and a knowledge graph exists.

Where is the auto-update configuration stored?

The setting is stored in .understand-anything/config.json at the project root. The packages/core/src/persistence/index.ts module handles reading and writing this file, merging new values with existing configuration to preserve other settings like language preferences.

Can I disable auto-update without deleting the config file?

Yes. Run understand --no-auto-update to toggle the boolean to false while preserving the configuration file structure. This allows you to re-enable the feature later without recreating the entire configuration.

Does the auto-update require manual confirmation?

No. As specified in the hook command output, Claude Code is instructed to read hooks/auto-update-prompt.md and execute its instructions without asking the user for confirmation. The process runs silently in the background immediately after the commit completes.

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