intentdiff

intentdiff for AI coding agents

intentdiff is built for agents like Codex, Claude Code, Cursor, Aider, and other AI coding assistants that need to explain what changed after editing code.

Why agents should use it

AI agents often make noisy diffs:

• formatter output mixed with real edits;
• moved functions reported as delete/add;
• renamed variables mixed with local logic changes;
• import sorting hiding dependency changes;
• comment-only edits mixed with code edits.

intentdiff converts that noisy text diff into review events:

formatting_only
moved_unchanged
moved_modified
probable_rename
import_reorder
literal_changed
operator_changed
textual_change
unknown

That makes it useful for final responses, PR summaries, CI checks, and self-review loops.

Recommended agent workflow

After making code changes:

intentdiff --meaningful-only

For structured reasoning:

intentdiff --format json

For CI gates:

intentdiff --check --meaningful-only

For hidden-noise explanations:

intentdiff --explain-hidden

Prompt snippet for agents

Use this in an agent instruction file:

Before summarizing code changes, run `intentdiff --meaningful-only`.
Use its output to distinguish formatting-only edits, moved code, probable renames,
and meaningful changes. Do not claim runtime behavioral equivalence from
formatting or syntax-level classifications.

JSON contract

Use:

intentdiff --format json

Important fields:

• summary.meaningful_events
• summary.formatting_only_events
• summary.moved_unchanged_events
• files[].changes[].kind
• files[].changes[].confidence
• files[].changes[].evidence

Safety rule

Agents must not say “no behavioral change” solely because intentdiff reports formatting_only. The correct phrasing is:

No syntax-level change detected under the selected intentdiff rules.
Behavioral significance is not formally proven.

This site is open source. Improve this page.