`detect-changes --brief` vs `update --brief` in Code-Review-Graph: Key Differences Explained

While both commands display identical Token Savings panels, detect-changes --brief performs a fast read-only query against the existing graph whereas update --brief first re-parses changed files to refresh the graph before running risk analysis.

The tirth8205/code-review-graph repository provides CLI utilities that map code relationships to optimize LLM context windows during code reviews. Understanding the distinction between these two --brief modes ensures you get accurate risk assessments without unnecessary computation overhead.

How the Commands Differ

The primary difference lies in graph preparation before the risk analysis executes. Both commands ultimately render the same four-line Token Savings panel, but they take different paths to get there.

detect-changes --brief: Read-Only Analysis

The detect-changes --brief command operates entirely in read-only mode. It queries the already-built graph structure and reports the impact of current changes without touching the filesystem. According to the implementation in code_review_graph/cli.py, this command specifically "Does NOT re-parse files" (lines 986-990), making it ideal when your graph is fresh.

Execution typically completes in approximately one second since it skips parsing overhead. Use this when you have the pre-commit hook or crg-daemon running to keep the graph synchronized.

update --brief: Incremental Update First

In contrast, update --brief performs an incremental refresh before analysis. It re-parses every changed file, updates the graph database, then delegates to the same analysis routine. This ensures the risk scoring reflects the actual current state of the codebase.

This command takes roughly five seconds to complete due to the parsing phase. Use it after a rebase, when handling large change sets, or whenever you suspect the graph might be stale.

Token Savings Panel Implementation

Both commands output the identical Token Savings panel generated from context_savings metadata attached to the response. As documented in docs/COMMANDS.md (lines 36-42), this panel displays:

• Baseline token count
• Size of the graph response
• Estimated tokens saved
• Per-category breakdown (Functions, Tests, Risk, Other)

The calculation logic resides in code_review_graph/context_savings.py (lines 124-138), where both commands pull the same metadata fields from the JSON response to render the boxed panel.

When to Use Each Command

Choose your command based on graph freshness and performance requirements:

• Use detect-changes --brief when the graph is actively maintained (via daemon or hooks) and you need immediate feedback. This is the default choice for iterative development workflows.

• Use update --brief after operations that may invalidate the graph state, such as rebasing branches, pulling remote changes, or working with large refactoring commits that touch many files.

Practical Code Examples

# Quick read-only view when graph is fresh (~1 second)

code-review-graph detect-changes --brief

# Full refresh and analysis when graph might be stale (~5 seconds)

code-review-graph update --brief

# Verify token calculations against the official tokenizer

code-review-graph detect-changes --brief --verify
code-review-graph update --brief --verify

Summary

• detect-changes --brief queries the existing graph without file parsing, as implemented in code_review_graph/cli.py at line 986.
• update --brief triggers an incremental graph refresh by re-parsing changed files before analysis.
• Both commands utilize the context_savings metadata from code_review_graph/context_savings.py (lines 124-138) to generate identical Token Savings panels.
• Choose read-only mode for speed (~1s) when the graph is current, or update mode (~5s) when freshness is uncertain.

Frequently Asked Questions

Can I use detect-changes --brief if my graph is stale?

No. Running detect-changes --brief on a stale graph produces risk analysis based on outdated file states. The command intentionally skips parsing to maximize speed, so it cannot detect changes made since the last graph update. Always run update --brief after rebasing or pulling remote changes.

Does update --brief always take longer than detect-changes --brief?

Yes. The update command incurs the overhead of re-parsing every changed file and updating the graph database before analysis begins. According to the source benchmarks, this adds approximately four seconds to execution time compared to the read-only variant.

What does the Token Savings panel actually measure?

The panel calculates LLM context window efficiency by comparing a baseline token count against the optimized graph response size. As implemented in code_review_graph/context_savings.py, it categorizes savings into Functions, Tests, Risk relationships, and Other metadata, showing exactly how many tokens the graph structure saves compared to feeding raw files to an LLM.

Is there a way to verify the token calculations?

Yes. Both commands accept a --verify flag that validates the estimated token counts against the official tokenizer used by the target LLM. This ensures the savings displayed in the panel match actual usage when the context is submitted to models like GPT-4 or Claude.

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