Zerostel

io.github.zerostelv0.1.2Updated Oct 5, 2026

Checkpoints, timeline and rewind for AI coding agents. Local, no telemetry.

VerifiedSTDIODesktop onlyDeveloper Tools Files & Storage Security & Monitoring

Overview

AI-generated overview

Records every step of AI coding agents locally and lets the assistant read its timeline and rewind files after a bad turn.

What it does: Zerostel is a local flight recorder for coding agents: it snapshots the project around each tool call that can change files, including shell commands, and keeps a timeline of prompts, commands, file changes, durations and token counts. Through MCP the agent can read that timeline and rewind when asked. It also supports user-defined guardrails that block a tool call or require confirmation, and produces a hash-chained log plus a shareable one-page report.
When to use it: Worth adding when you run coding agents that edit files or run shell commands and you want a way back after a destructive turn, a per-step record of what changed, and the same behaviour across several agents. Useful if you want the assistant itself to inspect its own session history or undo a step on request.
Requirements: Runs as a local process over stdio, installed via npm (npx zerostel install or a global install). Needs git and Node.js 20 or newer; standalone executables with Node bundled are offered for Windows, macOS and Linux. Agent integration uses each agent's hooks or plugin mechanism, so supported agents must be configured. No accounts, API keys or environment variables are declared.

Before you install

It is not a sandbox: network requests, deployments and database writes cannot be undone, and only captured states can be restored. Guardrails match what a tool call names, so a script that reaches a file without naming it gets through. The audit key (audit.key) protects the log chain, but anyone using your account can read it and rewrite a log; keep ~/.zerostel/** in a deny rule. Session logs may contain environment variable values on your machine. Rewinds write to project files.

Installation

In SourceWeft

Open Zerostel in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Zerostel]

Rewind any AI agent to point zero.

Zero trust for AI agents: assume they'll break something, record every step, and rewind the files they touched. A flight recorder and time machine for coding agents, with guardrails you set and a log that shows if it was edited.

Website · English · 繁體中文 · 简体中文 · 日本語

[npm] [CI] [License: Apache-2.0] [Node 20+] [Platforms] [Runtime dependencies: 0]

[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

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:

bash

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

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.

	Agent's own checkpoints	Commits / `git stash`	Zerostel
Changes made by shell commands	depends on the agent	only what you committed	✅ inside the project, plus files you list
Go back to a specific step	usually per prompt	per commit	✅ per tool call
Timeline of commands, files, tokens, time	partial	❌	✅
Log that shows if it was edited afterwards	❌	✅ (commit hashes)	✅
Your own rules: block or ask before a tool runs	per agent	❌	✅ same rules for every agent
Same behaviour across agents	❌ one each	✅	✅
Writes to your `.git`	some do	✅	❌ never
Shareable report of the session	❌	❌	✅

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

Agent	How	Status
Claude Code	hooks	✅ tested on real sessions
Codex	hooks (approve once with `/hooks`)	✅ tested on real sessions
Cursor	hooks	✅ CLI tested on real sessions; the CLI sends no prompt events, so undo goes one change at a time there. On Windows, start it from PowerShell: from Git Bash its hooks don't run
Gemini CLI	hooks (trusted folders only)	✅ tested end to end¹; for Code Assist Standard/Enterprise and paid API keys, since personal accounts moved to Antigravity in June 2026
Antigravity (CLI, desktop, IDE)	hooks	✅ tested end to end¹; it doesn't pass on the prompt text, so turns show as "New turn"
Copilot CLI	hooks (`~/.copilot/hooks`)	✅ tested on real sessions
opencode	plugin	✅ tested on real sessions
DeepSeek Harness	plugin	🧪 experimental (dsh itself is a developer preview); tested end to end¹
anything else (Aider, scripts…)	`zerostel run -- <command>` watches the files	✅ coarser: no tool calls, tokens or guardrails

¹ 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

bash

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

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


Commands	every command and option
Guardrails	how rules work, and tested recipes
Configuration	`~/.zerostel/config.json`
CI	the GitHub Action
MCP server	let the agent read its timeline and rewind when you ask
How it works	hooks, the shadow repo, safe rewinds, the audit chain
Zero trust	each principle, and what Zerostel does for it
Security model	what it protects and what it doesn't
Agents' own checkpoints	what each agent's undo brings back, with sources
FAQ	speed, disk use, git, jj, sandboxes, tokens

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.

License

Apache-2.0

Source: README.md at commit 04ba7c0

Tools

Tool metadata has not been indexed yet.

Version history

v0.1.2LatestOct 5, 2026