Zerostel

[npx zerostel demo: an agent turn deletes src/legacy with rm -rf and breaks the tests, then npx zerostel undo brings it back]

Quick start

npx zerostel install

Want to see it first? npx zerostel demo makes a throwaway project, plays one agent turn that deletes a folder and breaks the tests, and lets you undo it. No agent needed, and none of your projects are touched.

Then use your agent as usual. When it breaks something:

zerostel log          # what happened, step by stepzerostel undo         # put the files back to before the agent's last turnzerostel rewind 0     # or all the way back to point zero, where the session startedzerostel ui           # the same, clickable, in a local web page

What it does

• Record. Every prompt, tool call, command, file change, duration and token count, in one timeline per session: zerostel log in the terminal, or zerostel ui in a local web page.
• Rewind. A snapshot before and after every tool call that can change files, shell commands included. Undo a turn, go back to any step, or all the way to point zero; every rewind can itself be undone.
• Guard. Your own rules block a tool call, or make the agent ask you first, before it runs. The same rules for every agent.
• Verify and share. A hash-chained log that shows if it was edited, and a one-page report with a privacy mode for sharing.
• Stay local. Nothing is uploaded, ~/.zerostel is readable only by you, and your .git is never touched.

It's zero trust for AI agents: assume one can go wrong, see everything it does, and keep a way back (in practice). It isn't a sandbox: network requests, deployments and database writes can't be taken back. See Limits.

Why

Agents edit dozens of files, run rm, git checkout ., migrations and build scripts. When something goes wrong you're left asking what it did and how to get back.

Some agents have checkpoints of their own, and they differ a lot. Claude Code's rewind skips changes made through Bash. Copilot CLI tracks shell commands. Cursor and Codex each have their own model. If you use more than one agent, you get a different answer to "what changed and can I get it back" in each.

Zerostel records every supported agent the same way: a snapshot of the project around each tool call that can change files, a timeline of prompts, commands, files, time and tokens, and a report you can hand to someone else. It never touches your .git.

Details and sources: docs/comparison.md. The story behind it, with the incidents: What your coding agent's checkpoints can't bring back.

Supported agents and systems

¹ The real agent on Windows, with its model swapped for a scripted one: a prompt, a file write, a command, a call blocked by a rule, the end of the turn and an undo.

Experimental agents are installed only when you name them: zerostel install --agent deepseek. Reports from real sessions are welcome.

Zerostel doesn't care which model is behind the agent: Claude, GPT, Gemini, DeepSeek or a local one are all recorded the same way.

Windows, macOS and Linux (WSL too). CI runs every commit on all three with Node 20, 22 and 24.

Install

npx zerostel install          # one-off, nothing installed globallynpm install -g zerostel       # or keep the `zerostel` command around

You need git, and Node 20 or newer. No Node? Every release has a single executable with Node inside for Windows, macOS and Linux: download it from Releases and run zerostel install. Plugins for Claude Code, Codex, Antigravity and Gemini CLI, the agent skill, and how to check a download: docs/install.md.

Documentation

Something not working? Run zerostel doctor: it checks Node, git, each agent's hooks, your config and guardrails, and its output is safe to paste into an issue.

Limits

• Only states that were captured can be restored. Recording that starts after a deletion can't bring the file back.
• Inside one shell command there are no intermediate states: a file created and deleted by the same command is never seen. zerostel run snapshots when files settle, so it can miss short-lived files too.
• Outside the project, only files you list under watch are snapshotted, and only files under your home folder. On Windows, user environment variables (HKCU\Environment) are read around commands that change them and put back by rewinds; their values are kept in the session log on your machine, never in reports. Global packages are only listed, with the commands to undo them. Rewinds leave alone watched files that didn't exist at the target point. Everything else outside the project isn't covered; the timeline still shows the command that touched it.
• Not snapshotted, and listed by zerostel log when present: ignored folders (node_modules, dist/, anything in .gitignore), nested git repositories and submodules, linked folders (symlinks, junctions) and new files above maxFileMB.
• Agents started in your home directory or a drive root get a timeline but no snapshots.
• On case-insensitive file systems (Windows, macOS by default) a rename that only changes case, such as readme.md → README.md, isn't seen as a change.
• Under WSL, projects on the Windows drive (/mnt/c/...) are slow to snapshot. Keep them in the Linux file system.
• The audit chain shows a log was edited by anything that doesn't have your audit.key. Someone using your own account can read the key and rewrite a log completely; keep ~/.zerostel/** in a deny rule so the agent can't.
• Guardrails match what a tool call names. A script or command that reaches a file without naming it gets through.

Roadmap

• Done: recording and rewinding seven agents, point zero, web UI, shareable reports, verifiable logs, guardrails, MCP server, watched files outside the project.
• Next: signed reports anyone can verify without your key; recording calls to other MCP servers through a Zerostel gateway; test-output parsing to say which test broke; real-session validation of the experimental agents.
• Help wanted: test reports from macOS and Linux, and anything labeled help wanted.

Contributing

Questions and ideas are welcome in Discussions. Supporting a new agent means adding one adapter to src/agents/adapters.ts. See CONTRIBUTING.md and docs/architecture.md.

npm ci && npm test && npm run smoke

License

Apache-2.0