Try Demo
Docs
GitHub
Join the beta
GitHubnpm
Drift Detection Command

stamp context compare Command

Powerful context drift detector that works like Jest snapshots – compare current context against a baseline, approve updates, and track token cost changes.

Quick Start

# Auto-mode: Compare all context files (multi-file mode) stamp context compare # Auto-approve updates (like jest -u) stamp context compare --approve # Single-file: Compare two specific files stamp context compare old.json new.json # Multi-file: Compare two indices stamp context compare old/context_main.json new/context_main.json # Show per-folder token statistics stamp context compare --stats # Clean up orphaned files automatically stamp context compare --approve --clean-orphaned

Two Comparison Modes

The compare command supports two comparison modes:

1Multi-File Mode (Auto or Manual with context_main.json)

  • Compares all context files across your project
  • Uses context_main.json as the root index
  • Detects: ADDED FILE (new folders), ORPHANED FILE (removed folders), DRIFT (changed files), and PASS (unchanged files)
  • Shows three-tier output: folder-level summary → component-level summary → detailed per-folder changes

2Single-File Mode

  • Compares two specific context.json files
  • Detects added/removed/changed components
  • Shows detailed component-level diffs

What It Detects

In multi-file mode:

  • ADDED FILE – New folders with context files
  • ORPHANED FILE – Folders removed from project (but context files still exist on disk)
  • DRIFT – Changed files with component-level details
  • PASS – Unchanged files

In single-file mode:

  • Added components – new components in the new context
  • Removed components – components that existed in the old but not the new context
  • Changed components – components that exist in both but have differences in semantic hash, imports, hooks, exports, or other signature fields

Approval Workflow

The compare workflow mirrors Jest snapshots:

Interactive mode (local dev)

stamp context compare prompts to update all affected context files when drift is detected.

Auto-approve mode

stamp context compare --approve updates all files without prompting (CI-safe, like jest -u).

CI mode

Non-TTY environments never prompt and exit with code 1 when drift is detected.

Use --clean-orphaned with --approve to automatically delete stale context files from removed folders.

Token Statistics

With the --stats flag, the command shows per-folder token count statistics and deltas, allowing you to monitor how changes impact LLM context size across your project:

stamp context compare --stats

Token stats show the delta for each folder with changes, helping you understand the cost impact of modifications.

Exit Codes

0

PASS – no drift detected, or drift detected and approved/updated.

1

DRIFT detected and not approved, or an error occurred (file not found, invalid JSON, generation failure, etc.).