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

Note: The compare command does not compare styles by design. Style changes (CSS, Tailwind classes, inline styles, etc.) are intentionally excluded from comparison as they represent visual/presentation changes rather than structural or logical changes.

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.

Three Modes of Operation

1Auto-Mode (Recommended) - Multi-File

stamp context compare

What happens:

  1. Checks if context_main.json exists (errors if not found)
  2. Generates fresh context files based on your current code (all folders)
  3. Compares all context files using the indices
  4. Shows a three-tier output: folder-level summary → component-level summary → detailed per-folder component changes
  5. Prompts you to update if drift detected (in terminal)
  6. Exits with error if drift detected (in CI)

This is perfect for local development – just run it after making changes!

2Manual Mode - Single File

stamp context compare old.json new.json

What happens:

  1. Compares two specific context files (folder context.json files)
  2. Shows component-level differences
  3. Prompts to update old.json with new.json (in terminal)
  4. Exits with error if drift detected (in CI)

Use this when you want to compare specific snapshots or versions.

3Manual Mode - Multi-File

stamp context compare old/context_main.json new/context_main.json

What happens:

  1. Auto-detects that you're comparing context_main.json files
  2. Loads both indices and compares all referenced context files
  3. Shows three-tier output (folder summary + component summary + details)
  4. Prompts to update all files if drift detected (in terminal)
  5. Exits with error if drift detected (in CI)

Use this when comparing different branches, commits, or environments.

Output Format

Multi-File PASS (No Drift)

✅ PASS 📁 Folder Summary: Total folders: 14 ✓ Unchanged folders: 14 📂 Folder Details: ✅ PASS: src/cli/context.json Path: src/cli ✅ PASS: src/core/context.json Path: src/core ...

Exit code: 0

Multi-File DRIFT Detected

⚠️ DRIFT 📁 Folder Summary: Total folders: 15 ➕ Added folders: 1 🗑️ Orphaned folders: 1 ~ Changed folders: 2 ✓ Unchanged folders: 11 📦 Component Summary: + Added: 5 - Removed: 2 ~ Changed: 3 📂 Folder Details: ➕ ADDED FILE: src/new-feature/context.json Path: src/new-feature 🗑️ ORPHANED FILE: src/old-feature/context.json Path: src/old-feature ⚠️ DRIFT: src/components/context.json Path: src/components + Added components (2): + NewButton.tsx + Modal.tsx - Removed components (1): - OldButton.tsx ~ Changed components (2): ~ Card.tsx Δ imports - ./old-dependency + ./new-dependency Δ hooks + useState + useEffect ~ Button.tsx Δ hash old: uif:abc123456789012345678901 new: uif:def456789012345678901234 Token Δ: +641 (GPT-4) | +569 (Claude) ✅ PASS: src/utils/context.json Path: src/utils 🗑️ Orphaned Files on Disk: (These files exist on disk but are not in the new index) 🗑️ src/deprecated/context.json

Exit code: 1

Folder Status Indicators:

  • ➕ ADDED FILE – New folder with context file
  • 🗑️ ORPHANED FILE – Folder removed (context file still exists)
  • ⚠️ DRIFT – Folder has component changes
  • ✅ PASS – Folder unchanged

Orphaned File Cleanup

When folders are removed from your project, their context files may still exist on disk. Use --clean-orphaned to automatically delete them:

stamp context compare --approve --clean-orphaned

What happens:

  1. Detects orphaned files (exist on disk but not in new index)
  2. With --approve: Automatically deletes them
  3. Without --approve: Only reports them

Token Statistics

Add --stats to see per-folder token cost impact:

stamp context compare --stats

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

Exit Codes

CodeMeaningUse Case
0PASS – No drift detectedCI validation passed
0DRIFT approved and updatedUser approved changes or --approve used
1DRIFT – Changes detected but not approvedCI validation failed
1DRIFT – User declined updateLocal dev declined changes
1Error (file not found, invalid JSON, generation failed)Fatal error occurred

Key Points:

  • Exit 0 = Success (no drift OR drift was approved/updated)
  • Exit 1 = Failure (drift not approved OR error)
  • This matches Jest snapshot behavior exactly

Delta Types Explained

What is compared

  • Hash changes – component structure or logic changed
  • Import changes – import dependencies added/removed or order changed
  • Hook changes – React hooks usage changed
  • Function changes – functions declared in the module added/removed
  • Component changes – referenced React components changed
  • Prop changes – component API surface changed
  • Event/emit changes – event/callback interface changed
  • Export changes – export type changed (e.g., from export default to export const)

What is NOT compared

Styles – CSS classes, Tailwind utilities, inline styles, and other styling-related metadata are intentionally excluded. Compare Mode focuses strictly on structural and logical contract changes, not visual/presentation differences.