
time-machine
Every turn that changes files is a git snapshot: /timeline puts the working tree back as before any turn, Bash changes included. Undoable.
- version
- 0.1.3
- GitHub stars
- 288
Install
/plugin install time-machine@better-claudeRun it inside Claude Code after adding the marketplace with /plugin marketplace add midudev/better-claude.
Contents
Discovered from sourceAgents 1
Time Machine
A Claude Code mod: your files get a history of states, like an editor's undo tree. Every turn that changes files is a git snapshot off your history, and /timeline takes the working tree to any of them and back. Edits, writes and Bash all count: a sed, a codegen or an rm is undone like an Edit. Nothing is ever lost: your own unsaved changes are kept before a jump.
❯ /timeline
⏪ Time Machine 5 states
⠹ add rate limiting to the API 12s
│ 8 files +212 −40 · api/ ×5 · middleware/ ×2 · +1
◉ #4 add a migration for the users table 5m
│ + migrations/0007_users.sql +48 ~ db/schema.ts +12 −3
○ #3 another way to do it 7m
│ ~ src/auth.ts +9 −2
● #1 start of the session 14m
no files
──────────────────────────────────────────────────────────────────────
selected #3 · 7m current #4 · 5m jumped from —
› another way to do it: keep the sessions in Redis instead of the
database, and drop the cleanup job
⏎ go here: ~ src/auth.ts +2 −9 − migrations/0007_users.sql −48
↑↓ choose · ⏎ go undo redo
- One row per state, not per action. Going to a state moves the cursor
◉and the files; it adds no row. - You always see where the files are:
◉on their row and in the footer (selected is the state Enter goes to, current the one the files are in, jumped from the one they left on the last jump), or a yellow row when you changed files by hand since. - Enter goes to a state; choosing a row shows first which files would change.
u/rundo and redo: undo goes to the state the current one came from, redo to the newest state that came from it. - Branches are kept. Go back and let Claude take another way: the old way stays, dimmed (
○ … undone), one Enter away. - Your changes are never lost. Files changed by hand since the cursor are saved as a state (
your changes, kept before a jump) before any jump, so a jump needs no confirmation. - Claude hears it once. With your next prompt it reads which files differ from how it left them; five jumps that end where it left them say nothing.
- The turn under way shows at once, with a spinner and its time, the moment you send a prompt; its files and lines fill in as Claude edits, and it lands as a state when the turn ends (or goes, when it changed nothing).
- The files fit one line, however many: one or two by their short path; more as the total, the lines and the biggest folders under the one they all share (
8 files +212 −40 · api/ ×5 · tests/ ×2 · +1). - The footer stays put: docked beside the transcript it is pinned to the bottom, with the whole prompt of the chosen row (two lines), what Enter would do and the keys. Each part has a fixed height, so moving between rows only changes what is written; with more states than fit, the list is a window around the chosen row (
↑ 3 newer,↓ 2 older). - Nothing moves under the pointer: the running row is as tall as any other.
- From the prompt:
/timeline <n>,/timeline undo,/timeline redo.
How it differs from Claude Code's own checkpoints
Claude Code already rewinds the edits its file tools made (Esc Esc, /rewind). Time Machine snapshots the whole working tree with git instead, so it also brings back what Bash changed (a formatter, npm install touching the lockfile, a script that generates files, an rm), and the snapshots outlive the session: a resumed session finds them. The two live side by side.
What it never touches
- Your history: snapshots are commits no branch points at, kept by refs under
refs/time-machine/<session>/<n>.git logdoes not show them, but anything that reads every ref does:git log --all,gitk --alland the graph views (VS Code Git Graph, lazygit, Fork…) show one commit per state, branching off HEAD, with the turn's label (the first 60 characters of its prompt) as its message.git log --exclude='refs/time-machine/*' --allhides them.git push --mirrorwould publish them, untracked (not ignored) files and those labels included. - Your HEAD and branches: a jump moves the files, never HEAD. Going back past a commit or a checkout puts the old files back on the commit and branch you are on now, and the jump says so.
- Your staging area: they are built in an index of its own per session (
.git/time-machine-<session>.index), so what you staged stays staged. - Ignored files:
.env,node_modules/and anything else.gitignorematches are neither saved nor put back.
Install
/plugin marketplace add midudev/better-claude
/plugin install time-machine@better-claude
Configuration
| Option | Default | What it does |
|---|---|---|
| Keep snapshots for (days) | 7 | Older snapshots are dropped when a session starts; git's next gc frees their space. |
Limits
- It needs a git repository; elsewhere
/timelinesays so and nothing is snapshotted. - A snapshot stores every file that is not ignored, untracked ones included. A large untracked file that is not in
.gitignoregrows.gituntil its snapshot is dropped, and a file of secrets that is not in.gitignore(a.env.local, a key) is kept in.gitthe same way: add such files to.gitignorebefore the session starts. One already snapshotted leaves the next snapshots once it is ignored, and.gitwhen its snapshots are dropped and git collects them. - A jump waits for the turn to end, and for any tool still writing (a background agent's included): until then it refuses. It also refuses when the files it would write include an ignored one on disk, or more than can all be checked.
- A jump puts files back, not commits: if HEAD has moved since the state (a
git commit, agit checkout), the files go back and HEAD and the branch stay, sogit statusshows the old files as changes on top of the new HEAD. Nothing is lost, and the jump message warns about it. - A turn whose tools leave the files as they were (a test run that writes nothing) adds no state.
- A Bash command that only looks (
ls,cat,grep,rg,git status,git log, … chained with|,&∨) takes no snapshot. Any redirection,$(…),tee,xargs,find -deleteor-exec, or a command it does not know, does: when unsure, it snapshots.
Cost
Measured on a repository of 12,800 files (Apple Silicon):
| Step | Time |
|---|---|
| First snapshot of a session | 283 ms |
| Start of a turn that changes files | 154 ms |
| End of a turn | 142 ms |
| A jump back | ~170 ms |
Most of it is git add -A walking the tree, git's own floor; about 35 ms is the check that keeps files the .gitignore now matches out of the snapshots. The index starts as a copy of the repository's, which carries the stat data of every file (without it the first snapshot hashes the whole tree: 491 ms).
How it works
One hooks module (hooks/register.tsx) over plain modules in src/, each tested on its own with node --test:
src/git.js: snapshots, moves and refs, run through$.process.run.src/states.js: the history as data: which states the files are made of, the next id, the merge after a hot reload.src/tools.jsandsrc/bash.js: which tool calls may write, Bash by its command. When unsure, a call may write and gets its snapshot.src/format.js: how states and their files read, in the pane and in the transcript.
The hooks:
tool.callon any tool that may write (seesrc/tools.js: not Read, Grep, a Bash command that only looks or an MCPget_/list_tool): the first one of a turn writes the tree as it is before it runs (add -Aandwrite-treein Time Machine's own index, seeded from HEAD withread-tree -m HEADwhenever HEAD moves).turn.completewrites the tree again. Unchanged, nothing is kept. Changed, the turn becomes a state (commit-treeand a ref), its parent the state holding the starting tree, or a newstart of the session/changes outside Claudestate when none does.- A jump reads the tree, keeps it as a state when it is no state's, then moves the files with
read-tree -m -u <now> <target>: files the target lacks are removed and the rest written. prompt.submit, after jumps, compares the tree with the one Claude's last turn left and adds one note to the prompt'scontextwhen they differ.- The states and the cursor live in
$.state(the pane redraws from them) and in$.storeunder the session's id.
Development
claude plugin validate ./plugins/time-machine # from the repository root
claude plugin test ./plugins/time-machine # hooks/register.test.tsx against the engine
node --test "plugins/time-machine/test/*.test.js" # src/: git against a real git, the rest pure
MIT © DiegoMarty
Hooks 1
Sponsors
Details
- Marketplace
- midudev/better-claude
- Source
- plugins/time-machine
- Category
- Productivity