Search, rewrite, say why, replay: AI agents read, search and rewrite files with a reason for every step, recorded on a tape you can replay frame by frame in VSCode or Vim.

日本語 | English

_{srwr = Search · rewrite · say why · replay}

_{The real srwr view in Vim, stepping through a session: a reason line, then the code it is about.}

Contents

• ✨ Features
• 🚀 Install
• 🧭 How to use it
• 👀 Viewing a tape
• 🤝 Sharing a tape
• 📚 Documentation
• 💬 Interactive guide
• 📄 License

✨ Features

• ✍️ Its own tools, nothing else: the AI reads with look, changes with edit and creates with new. By default there is no other way to touch a file, so nothing slips past the record
• 🔎 Search, then change: look can search a file or the whole project and hands back a token that edit takes. edit can also name its place by file and expect, or change part of a line with old and new, and edits changes many places at once
• 🧾 A reason for every step: each call carries a why, and an empty one is refused
• 🎞️ Frame by frame: replay what the AI did one frame at a time, with the reason line above the code it is about
• 🧩 VSCode and Vim: the same screen in the VSCode extension and in a plain Vim (srwr view, nothing to install)
• 📡 Live: follow a tape while the AI is still writing it, and jump back to the newest frame when you want
• 🔍 Changes from outside are not lost: if a file changes outside srwr, the next call notices and shows it as a side-by-side diff
• 🧯 Failures are recorded too: a call that was turned away is on the tape. Choose what you see: look, edit, outside changes, failures
• 🏷️ Sessions with a title, and a way back from git: the AI can name its session; srwr trace tells which operation, and which why, wrote the lines of a commit
• 🔒 Secrets stay out: .env, keys and anything in .srwrignore are never put on a tape
• 📦 One binary, no dependencies: a single Go binary, no cgo, Linux, macOS and Windows
• 🕒 Times that make sense: tapes keep UTC, and screens show your own time zone
• 🌍 English and Japanese: English by default; SRWR_LANG=ja for Japanese

Status. srwr is 0.x: tool inputs, the tape format and the screens may still change before 1.0. The tapes written so far (format versions 1 and 2) are all read.

🚀 Install

You need the srwr binary first. It is what the AI talks to, and what the editors start to read tapes.

go install github.com/amisonnet8/srwr/cmd/srwr@latest

Prebuilt binaries for Linux, macOS and Windows are on GitHub Releases. Put the binary on your PATH.

To view in VSCode, install the extension srwr-view as well (it does not contain srwr; see its README). To view in Vim, you need Vim 9.0.0784 or later and nothing else.

🧭 How to use it

1. Set up your project (once). This registers srwr for Claude Code and, by default, forbids its Edit and Write tools so that every change goes through look, edit and new:

   cd your-project
   srwr init

   What does srwr init write?

   File	Content
   .srwr/	The directory for tapes, and the key
   .mcp.json	Registers srwr mcp, the MCP server the AI uses
   .claude/settings.json	The hook that records what the AI reads, and the ban on Edit/Write (srwr init --lenient keeps them allowed)
   .gitignore	Ignores the key, the lock, the pointer to the current session and the backups, not the tapes

   Existing settings are kept, and running it again changes nothing. Details: docs/reference/cli.md.

2. Let the AI work. Every look, edit and new goes on a tape in .srwr/tapes/:

   What does a tape look like?

   A tape is a JSONL file, one event per line. This is a look (the AI looks at lines 9 to 11) and the edit that follows (shortened: ts is left out and the texts are cut):

   {"v":2,"seq":2,"type":"look","file":"main.go","startLine":9,"endLine":11,"why":"greet is what main prints: check what it does when the name is empty","selection":"sel_041061E48KVH3K24RN324MN2","source":"mcp"}
   {"v":2,"seq":3,"type":"edit","file":"main.go","from":"sel_041061E48KVH3K24RN324MN2","startLine":9,"endLine":11,"oldText":"…","newText":"…","why":"An empty name printed \"hello \" with nothing after it, so greet a stranger instead","source":"mcp"}

   The format is in docs/reference/tape.md.

3. Look at what happened (below).

A whole round with every command, from srwr init to tidying up the tapes, is in docs/examples/workflow.md.

👀 Viewing a tape

Where	How
Vim	srwr view (pick a tape from the list), or srwr view <tape>. ]] forward, [[ back, q to close. srwr view --live follows a tape being written
VSCode	Install the extension, then srwr at the left edge → Operations → Open a tape or Start live view
Terminal	srwr tapes lists the tapes of the project. git show HEAD | srwr trace tells which operations (and which why) wrote the lines of a commit

_{srwr-view in VSCode. Blue is a look, orange is an edit, purple is a change from outside.}

You step with Back and Forward; there is no autoplay, because the point is to read each reason. Details: VSCode and Vim.

🤝 Sharing a tape

A tape holds the whole text of the files it touched, and it replays on its own. Hand it over with srwr tapes path <tape>, and the other person opens it in their own editor.

• 🔑 Never share .srwr/key. It is not needed for replay
• 🔒 Files with secrets are not recorded (.env, *.pem, *.key, SSH keys, and what you list in .srwrignore). Check the tape before you share it all the same
• 🕒 A tape keeps UTC; the other person sees their own time zone

📚 Documentation

You want to	Read
Use srwr	Command line · Settings · The tools the AI uses
View in an editor	VSCode · Vim
Read tapes or add an editor	Tape format · View server protocol
Know how it is built	Overview · Decisions · Limits

Everything is in docs/, in English and in Japanese.

💬 Interactive guide

Ask questions and explore srwr in a conversation: the srwr guide, made with Gemini Notebook.

📄 License

MIT © amisonnet8

⬆ back to top