Watch Mode
Keep your context files fresh automatically with incremental rebuilds. Watch mode detects file changes and updates only affected bundles.Need guardrails? Strict Watch detects breaking changes (removed props/events/functions, etc.) and tracks violations during your coding session.
Why Watch Mode?
Watch mode keeps your AI context always up-to-date as you code. Instead of manually regenerating context files, it detects changes and incrementally rebuilds only the affected bundles.
Instant Context
Zero-cost access for MCP tools
Incremental Rebuilds
Only affected bundles update
Change Detection
See what changed (props, hooks, state)
Strict Watch
Detect breaking changes + track violations
Tip: Regular watch mode shows diffs. Add --strict-watch to classify breaking changes and keep a violations report for the session.
Syntax
# Start watch mode (recommended)
stamp context --watch
stamp context -w
# Alternative syntax
stamp context watch
# With options
stamp context --watch --log-fileWatch mode runs in the foreground and monitors your project for changes. Press Ctrl+C to stop. If you used --strict-watch, the session will summarize violations on exit.
How It Works
Initial Build
Generates all context files (like stamp context) and initializes the watch cache
File Monitoring
Watches for changes to .ts, .tsx files (and style files when enabled)
Debounced Rebuilds
Changes are batched with a 500ms delay to handle rapid edits efficiently
Incremental Updates
Only affected bundles are rebuilt, not the entire project
Strict Watch (Optional)
With --strict-watch, changes are classified into violations (errors/warnings) relative to the baseline when watch mode started.
Options
| Option | Alias | Default | Description |
|---|---|---|---|
--watch | -w | false | Enable watch mode for continuous file monitoring |
--strict-watch | — | false | Strict watch mode — detect breaking changes and track violations (errors/warnings) relative to baseline |
--log-file | — | off | Write structured change logs to .logicstamp/context_watch-mode-logs.json |
--debug | — | false | Show detailed hash/diff information on changes |
--quiet | -q | false | Suppress verbose output (show only errors) |
--include-style | — | false | Watch style files and include style metadata in generated context |
--profile watch-fast | — | default | Use lighter style extraction for faster rebuilds |
--depth <n> | — | 2 | Dependency traversal depth for bundles |
All standard stamp context options work with watch mode. --strict-watch adds violation tracking on top of normal diffs.
MCP Integration
Watch mode is designed to work seamlessly with the LogicStamp MCP server. When watch mode is active, MCP tools can skip expensive regeneration and access fresh context instantly.
MCP Workflow with Watch Mode
- Start watch mode in a terminal:
stamp context --watch - MCP tool calls
logicstamp_watch_statusfirst - If watch mode is active, skip
refresh_snapshotentirely - Go directly to
list_bundles→read_bundle
With watch mode active, LLM tools get instant access to fresh, pre-generated context without any regeneration overhead.
Watch Status & Logs
Watch mode writes a status file at .logicstamp/watch_status.json that other tools (like MCP) can use to detect if watch mode is running.
{
"active": true,
"projectRoot": "/path/to/project",
"pid": 12345,
"startedAt": "2026-01-21T11:33:48.260Z",
"outputDir": "/path/to/project"
}The status file is created when watch mode starts and cleaned up when watch mode stops.
Example Workflows
# Basic watch mode
stamp context --watch
stamp context -w
# Watch with style metadata
stamp context --include-style --watch
# Watch a specific directory
stamp context ./src/components --watch
# Watch with debug output (shows hash changes)
stamp context --watch --debug
# Watch with structured change logs (for change notifications)
stamp context --watch --log-file
# Strict watch mode - track breaking changes and violations
stamp context --watch --strict-watchWhat Changes Are Detected?
Watch mode tracks semantic changes to your components, not just file modifications.
Component Changes
- • Props added/removed/modified
- • State variables changed
- • Hooks added/removed
- • Emitted events changed
Structural Changes
- • New components added
- • Components deleted
- • Import dependencies changed
- • Export signatures modified
Note: Regular watch mode shows changes, but doesn't classify them as breaking. Use --strict-watch to detect breaking changes (removed props/events/functions, etc.) with violation tracking.
Strict Watch Mode
Strict watch mode tracks breaking changes and violations during development. It compares the current contracts against the baseline (the state when watch mode started) and reports what's currently broken.
# Enable strict watch mode
stamp context --watch --strict-watch
# Combine with style metadata
stamp context --include-style --watch --strict-watchState-based semantics
Violations reflect the current state relative to baseline (like git diff). If you fix/revert breaking changes, the report is deleted (no violations = no report).
Exit behavior
Watch mode is for development awareness, not CI enforcement. On Ctrl+C, it exits with signal code (130) regardless of violations.
For CI with exit codes, use stamp compare instead.
Best Practices
Start watch mode when beginning a coding session
Run stamp context --watch in a dedicated terminal alongside your dev server
Use strict watch during refactors
Add --strict-watch to catch breaking changes early and keep a violations report while you refactor
Use with MCP for the best experience
MCP tools automatically detect watch mode and skip regeneration, giving you instant context access
Add .logicstamp/ to .gitignore (automatically added when you run stamp init)
The cache directory, watch status files, logs, and strict watch reports shouldn't be committed to version control.
Use --log-file for debugging & notifications
Enable logging to see structured rebuild info and “what changed” entries
Next Steps
Explore best practices, or jump to usage for more workflows (including strict watch during refactors).