TimeTravel Code
Your code has a past. Travel back to it.
TimeTravel Code keeps an automatic, local timeline of your files, so you can inspect, compare and restore earlier versions, including changes you never committed. It needs no account, makes no network requests and uses no AI service.
Quick start
- Install the extension and open a folder.
- Choose Enable Tracking when prompted (or run TimeTravel: Resume Tracking).
- Edit and save files as usual. Open the TimeTravel icon in the Activity Bar, or run TimeTravel: Open Timeline.
- Click a snapshot to diff it with the current file. Use Restore… to bring it back. Your current version is saved first, and you can undo the restore.
Features
| Area |
What you get |
| Automatic snapshots |
Baseline when a file is first tracked, a snapshot on every save, and automatic checkpoints for significant unsaved edits (debounced, rate-limited). Identical consecutive content is never stored twice. |
| File operations |
Creation, deletion and rename of files and folders are recorded; history follows a renamed file. |
| Timeline |
Chronological, newest first, grouped by day, with relative and absolute times, change size (+/− lines), badges for Current version, Restored, Recovery point and checkpoint names. Search, file/folder filter, type filter, date range, pagination, a Changed files summary for a time range, and keyboard navigation. |
| Travel |
Open a snapshot read-only, diff with current / previous / any other snapshot (native diff editor), step to older or newer snapshots. |
| Restore |
Diff preview, explicit confirmation, automatic recovery point (including unsaved editor changes), one-click undo. |
| Checkpoints |
Named, multi-file checkpoints (for example "Before refactor"). Compare a checkpoint with the workspace, see which files changed, and restore all, some or just one file, previewing each change first. |
| Retention |
Max age, max storage, max snapshots per file, manual clean-up, integrity check. Snapshots in named checkpoints are never pruned automatically. |
| Privacy |
Everything stays on your machine. Common secret files and generated folders are excluded by default. |
Commands
All commands are in the Command Palette under TimeTravel:
Open Timeline · Create Checkpoint · View File History · Compare With Current · Compare Snapshots · Restore Snapshot · Pause Tracking · Resume Tracking · Search History · Manage Exclusions · Clean Up History
Also available: Compare With Previous Snapshot, Select / Compare With Selected Snapshot, Go to Older / Newer Snapshot, Restore / Compare / Rename / Delete Checkpoint, How It Works, Show Log. The status bar item opens a quick-actions menu. Right-click a file in the Explorer or an editor tab and choose TimeTravel: View File History.
Restoring only part of a file
Run Compare With Current on a snapshot. In the diff editor the snapshot is on the left and your file is on the right; use the arrows in the diff gutter to move individual changes from the snapshot into your file. This uses the editor's own, safe, undoable edit mechanism.
Privacy and safety
- Local only. History is stored in VS Code's per-workspace storage folder on your computer (not inside your project). Nothing is uploaded; there is no telemetry.
- What is tracked. Text files you open, edit or create inside the workspace. TimeTravel does not scan or copy the whole project, so huge workspaces are fine.
- What is not tracked. Excluded paths, binary files (files containing NUL bytes) and files over
timetravel.maxFileSizeKB. Excluded files are never stored.
- Restores are explicit. You always see the diff and confirm. The current version is preserved as a recovery point before anything is overwritten. If a snapshot is damaged, the restore stops before touching your file.
- Path safety. Snapshot ids and stored paths are validated; restores cannot write outside the workspace, including through symlinks. Nothing stored in a snapshot is ever executed.
- Git info. If enabled, the branch and short commit are recorded using
git run without a shell, only in trusted workspaces. Git is not required.
Local history is not a substitute for backups or version control. Keep committing to Git and backing up your work.
Exclusions
timetravel.exclude is a list of workspace-relative glob patterns (*, **, ?, {a,b}):
secrets (a plain name) matches a file or folder called secrets anywhere.config/private/** matches everything under that folder.**/*.sqlite matches by extension.
Defaults exclude node_modules, .git, dist, build, out, .next, coverage, virtual environments, target, .env*, *.pem, *.key, *.p12, *.pfx, SSH keys, minified files, source maps and .DS_Store. Setting timetravel.exclude replaces the default list, so copy the entries you still want.
With timetravel.respectGitignore (default on) the root .gitignore is also honoured. Matching is simplified: patterns, ! negation, a leading / (anchored), and a trailing / (directory) are supported; nested .gitignore files, global ignore files and .git/info/exclude are not read. Treat it as a convenience, and use timetravel.exclude for anything sensitive.
Use TimeTravel: Manage Exclusions to add or remove patterns. When you exclude something that already has history, you are offered the choice to delete that history.
An annotated example configuration ships with the source in docs/example-settings.json.
Settings
| Setting |
Default |
Meaning |
timetravel.debounceMs |
2000 |
Quiet time after typing before evaluating an automatic snapshot |
timetravel.snapshotOnSave |
true |
Snapshot on every save |
timetravel.autoSnapshot.minIntervalSeconds |
60 |
Minimum gap between automatic snapshots of one file |
timetravel.autoSnapshot.minChangedCharacters |
120 |
Minimum change size for an automatic snapshot |
timetravel.maxFileSizeKB |
1024 |
Larger files are not tracked |
timetravel.exclude |
see above |
Never-track patterns |
timetravel.respectGitignore |
true |
Also honour the root .gitignore |
timetravel.retention.maxAgeDays |
30 |
0 = keep forever |
timetravel.retention.maxStorageMB |
500 |
Oldest unprotected snapshots go first |
timetravel.retention.maxSnapshotsPerFile |
200 |
Oldest unprotected snapshots go first |
timetravel.recordGitInfo |
true |
Record branch and short commit |
Settings can be set per workspace in .vscode/settings.json.
How storage works
Content is stored once per unique hash (gzip-compressed, SHA-256 addressed), so identical versions cost nothing extra. Metadata is an append-only index.jsonl, replayed on start, compacted when it accumulates dead records, and written atomically. A crash leaves at most a temporary file, which is cleaned up on the next start. Unreadable index lines are skipped (a backup copy is kept), and every snapshot's hash is verified when it is read.
Retention runs in the background every 15 minutes (in memory planning, then small deletions) and when you run Clean Up History. If checkpoints alone exceed the storage limit you are told, rather than having protected history silently discarded.
Known limitations
- Local folders only (not virtual or remote file systems).
- Text is stored as UTF-8. For files in another encoding, snapshots hold the text as VS Code decodes it, and a restore to a closed file writes UTF-8 (a restore into an open editor keeps the editor's encoding settings).
- A leading UTF-8 BOM is not preserved when a restore writes to a closed file.
- A checkpoint contains the files that were tracked or open when it was created; files you never opened are not part of it.
- Per-file Git info uses the first workspace folder's repository in multi-root workspaces.
- AI summaries are not part of this release.
src/ai/provider.ts defines an opt-in provider interface (local-only by default, explicit consent required for anything that leaves the machine) for future use.
Development
npm install
npm run compile # TypeScript -> out/
npm run lint # ESLint
npm run test:unit # fast unit tests (Node's built-in test runner)
npm run test:integration # launches a real VS Code (downloads it on first run)
npm test # compile + unit tests
npm run package # builds timetravel-code-<version>.vsix
Press F5 in VS Code to launch an Extension Development Host.
On Linux without a display, run the integration tests under Xvfb: xvfb-run -a npm run test:integration. Set VSCODE_TEST_VERSION=1.85.0 to test against the minimum supported VS Code.
Install locally
code --install-extension timetravel-code-0.1.0.vsix
or Extensions: Install from VSIX… in the Command Palette.
Publish
Add a repository URL to package.json, create a publisher, then npx vsce publish (VS Code Marketplace) and npx ovsx publish is optional for Open VSX.
Layout
src/core/ VS Code-independent logic (store, capture, retention, history, restore, exclusions, diff stats)
src/ extension lifecycle, tracker, commands, flows, engine, diffs, status bar
src/views/ tree views, timeline webview, onboarding page
src/ai/ optional summary-provider interface
src/test/unit/ unit tests
src/test/integration/ VS Code extension-host tests
media/ icon, activity bar icon, webview CSS/JS
License
MIT. See the LICENSE file.
