How to Configure Understand Anything: JSON Settings and CLI Flags

You configure Understand Anything through a JSON file at .understand-anything/config.json that is automatically created on first run and updated via CLI flags like --language and --auto-update.

Understand Anything is a multi-agent plugin that builds a knowledge graph of your codebase. Configuration persistence is handled through a central JSON file controlled by command-line flags defined in understand-anything-plugin/skills/understand/SKILL.md. This guide covers the core options, lifecycle, and programmatic interfaces for managing these settings.

Configuration File Location and Structure

The plugin stores all persistent settings in .understand-anything/config.json at your project root. This file uses a simple key-value map structure that the persistence module reads and writes generically, allowing future extensions without core code changes.

Core Configuration Options

The configuration file controls two primary behavioral settings:

autoUpdate — A boolean flag that determines whether the post-commit hook automatically rebuilds the knowledge graph after each git commit. When true, the hook defined in hooks/hooks.json triggers incremental updates.

outputLanguage — An ISO-639-1 language code (e.g., en, zh, ja). This controls the language for all generated summaries, tags, tours, and UI labels throughout the analysis.

Configuration Lifecycle

The configuration progresses through four distinct phases during plugin usage.

First Run Initialization

When no configuration exists, the skill parses any --language flag provided. If omitted, it attempts to infer your system language, prompts for confirmation once, and then persists the result. The default state writes autoUpdate: false and outputLanguage: "en" (or your detected language) to the config file.

Modifying Language Settings

Supplying --language <code> during execution overrides the stored value and immediately rewrites config.json. This persists your choice for all future analyses without requiring the flag again.

Toggling Auto-Update

Using --auto-update writes autoUpdate: true to the configuration, while --no-auto-update sets it to false. These flags update the stored boolean directly in the JSON file.

Incremental Execution

All subsequent plugin runs read .understand-anything/config.json to determine execution strategy. The persistence module checks these values to decide whether to rebuild the entire graph, perform an incremental update, or skip generation entirely.

Implementation Details

The core package implements configuration management through specific modules in understand-anything-plugin/packages/core/src/.

Persistence Module

In packages/core/src/persistence/index.ts, the loadConfig function handles file I/O operations:

const CONFIG_FILE = "config.json";
export async function loadConfig(projectRoot: string): Promise<ProjectConfig> {
  // Reads and returns configuration from .understand-anything/config.json
}

This module loads the configuration at startup and provides the generic read/write capabilities that support the simple map structure.

Type Definitions

The ProjectConfig interface is defined in packages/core/src/types.ts (lines 118-120):

interface ProjectConfig {
  autoUpdate: boolean;
  outputLanguage: string;
}

This type matches the JSON structure persisted to disk.

Practical Configuration Examples

Changing Output Language

Generate all summaries and tags in Chinese by running:

/understand --language zh

The first non-English execution prompts for confirmation; your answer is saved in .understand-anything/config.json alongside the autoUpdate setting.

Enabling Automatic Updates

Turn on the post-commit hook to automatically maintain your knowledge graph:

/understand --auto-update

This writes {"autoUpdate": true} to the configuration file. To disable automatic updates later:

/understand --no-auto-update

Inspecting Configuration Directly

View current settings using standard shell commands:

cat .understand-anything/config.json

Example output:

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

Programmatic Access

Import the persistence module to read configuration values in TypeScript:

import { loadConfig } from "@understand-anything/core/src/persistence";

async function readSettings(projectRoot: string) {
  const cfg = await loadConfig(projectRoot);
  console.log("Auto-update enabled:", cfg.autoUpdate);
  console.log("Output language:", cfg.outputLanguage);
}

The loadConfig function returns a ProjectConfig object containing the current autoUpdate and outputLanguage values.

Summary

• Configuration is stored in .understand-anything/config.json at the project root.
• Two core options control behavior: autoUpdate (boolean) and outputLanguage (ISO-639-1 code).
• The file initializes automatically on first run with language detection and confirmation.
• Update settings via --language, --auto-update, and --no-auto-update CLI flags.
• The loadConfig() function in packages/core/src/persistence/index.ts provides programmatic access.

Frequently Asked Questions

Where is the Understand Anything configuration file stored?

The configuration file is located at .understand-anything/config.json in your project root. According to the source code in packages/core/src/persistence/index.ts, the loadConfig function specifically reads from this path to initialize the ProjectConfig type.

How do I permanently change the output language?

Run /understand --language <code> using an ISO-639-1 language code such as zh for Chinese or ja for Japanese. This updates the outputLanguage field in config.json immediately and persists for all future analyses without requiring you to supply the flag again.

What does enabling auto-update actually do?

When autoUpdate is set to true via /understand --auto-update, the git hook defined in hooks/hooks.json monitors your repository. After each commit, it checks this flag and triggers an incremental update of the knowledge graph automatically, eliminating the need to manually run the /understand skill.

Can I manually edit the configuration file?

Yes. Since packages/core/src/persistence/index.ts reads the file generically as a simple map, you can manually edit .understand-anything/config.json to adjust values or add future-compatible keys. Changes take effect on the next plugin execution when loadConfig parses the updated file.

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