How StateSense Works
Architecture and internals — read time ~5 min
The core idea
StateSense runs entirely inside VS Code as a local extension. There is no server, no cloud sync, and no account. Everything — snapshot data, diffs, metadata — is stored on your machine in the extension's storage directory.
The extension watches your workspace for meaningful changes and automatically saves a lightweight snapshot of every file that changed. When you need to go back, you pick a snapshot, preview the impact, and restore — complementing your git workflow, not replacing it.
The snapshot pipeline
When a change is detected, StateSense runs it through a four-stage pipeline:
Listens to VS Code's onDidSaveTextDocument and workspace file system events. Debounces rapid saves (10 seconds) to avoid snapshotting every keystroke.
Decides whether a change is worth snapshotting. A single-file edit must cross a 10-line threshold. Multi-file edits (≥2 files) are always captured. File creations and deletions always trigger a snapshot.
Computes a per-file diff between the new snapshot and the last one. Only changed files are stored — unchanged files are referenced from the previous snapshot, keeping storage minimal.
On Free: enforces the 7-snapshot limit, pausing new snapshots when the cap is reached. On Pro (unlimited): no cap. In both cases, when you manually run Clear Snapshots, a pinned snapshot and its chain is kept. Git events (commit / branch switch) bypass all of this and wipe everything.
Snapshot triggers
A snapshot is created automatically when any of the following occur:
- A single file is saved with 10 or more lines changed
- 2 or more files are saved within a short window (configurable via
multiFileThreshold) - A file is created or deleted in the workspace
- A large aggregate change is detected across many files (configurable via
largeChangeThreshold)
You can also create a snapshot at any time via the Command Palette: StateSense: Take Snapshot.
Git-aware cleanup
When a git repository is open, StateSense integrates with git to keep your snapshot history clean automatically:
- When you commit, snapshots from before the commit are cleared — your code is now in git history.
- When you switch branches, snapshots from the previous branch are cleared — they belong to different work.
Both events clear all snapshots including any pinned one. Pins only survive the manual Clear Snapshots command — not git events.
Note: git-aware cleanup requires VS Code's built-in git extension and an open git repository. Without git the extension is severely limited — snapshots accumulate with no automatic reset points and some restore edge-cases depend on git to resolve correctly. See Git Integration for details.
Storage format
Each snapshot stores only the files that changed since the last snapshot (incremental storage). Unchanged files are referenced by pointer rather than duplicated, keeping the footprint small even with a long history.
File contents are compressed before storage. All data lives in VS Code's extension storage directory on your local machine — nothing is transmitted anywhere.
Restoring a snapshot
Restoring is a three-step process designed to prevent surprises:
- Select a snapshot from the StateSense sidebar.
- Preview — a restore preview panel lists every file that will change, with a diff for each. You can review the full impact before committing.
- Confirm — click Restore and StateSense writes each changed file back to disk. VS Code refreshes open editors automatically.
A snapshot is automatically taken of your current state before a restore, so you can always undo the restore if needed.