Map Watcher

Map watcher

The project map is the index sp_map, sp_symbol and sp_lines read from. When files change on disk the map can drift, which makes scoped reads return stale ranges or "no symbol" results. The map watcher closes that window.

What it does

When enabled, the MCP server watches the project tree and rebuilds the in-memory map after relevant edits, so the next sp_symbol or sp_lines call sees the current shape of the file. The disk-side map.md and map.json are refreshed on the same beat.

The --watch-map flag

Start the server with the flag, or set the env var:

node dist/mcp/index.js --watch-map
# or
SLIPSTREAM_WATCH_MAP=1 node dist/mcp/index.js

In Claude Code the plugin opts in automatically. In Cursor, Windsurf, Antigravity and JetBrains add the flag to the args array of the slipstream MCP entry.

Debounce window

File-system events fire in bursts (a save triggers several inotify or FSEvents callbacks). The watcher coalesces events on a 300 ms debounce: the rebuild runs once, 300 ms after the last event in a burst. This keeps a save-on-every-keystroke editor from rebuilding the map continuously.

The window is tunable via SLIPSTREAM_WATCH_DEBOUNCE_MS. Setting it to 0 rebuilds on every event (not recommended outside debugging).

When a rebuild fires

The watcher triggers on:

• Source-file writes inside the project that match the map's include globs (TypeScript, JavaScript, Python, Go, Rust, by default).
• File creations and deletions inside those globs.
• Renames seen as a delete plus a create.

When a rebuild does NOT fire

The watcher deliberately ignores:

• Anything inside node_modules, .git, dist, build, .next, .turbo, .venv and other build directories.
• Anything inside .claude/slipstream/ (its own state, including observations/, map.md, map.json, budget.json and the dashboard log).
• Lock files (package-lock.json, pnpm-lock.yaml, yarn.lock, Cargo.lock, go.sum).
• File-attribute-only changes (chmod, atime, mtime touch with no content change).
• Files outside the configured map root.

This list keeps the watcher from rebuilding on its own writes (which would otherwise loop) and from rebuilding for changes that cannot affect the symbol surface.

---

SarmaLinux . sarmalinux.com . Repository