DEV Community

Cover image for I built an offline, no-AI tool that turns your terminal history into runbooks
Hamza Mansoor
Hamza Mansoor

Posted on

I built an offline, no-AI tool that turns your terminal history into runbooks

#showdev #opensource #python #devops

Every team has that one deploy only a single person really knows how to run. The steps live in their head, and the doc that's supposed to explain it is three commands out of date.

I got tired of that, so I built runscribe: you record a terminal session the way you'd normally work, and it turns what you did into a clean, re-runnable runbook. No screen recording, no wiki page that rots, and — deliberately — no AI.

  • 🔒 100% local. No account, no network, no telemetry. Nothing is uploaded, ever.
  • 🤖 No AI. The runbook is produced deterministically from what actually ran. Same session in, same runbook out.
  • 📝 Plain Markdown or HTML out. Hand-editable, diff-able, readable without runscribe installed.
  • ▶️ It re-runs. The runbook isn't just text — hand it back and step through it later.

The loop

1. Record — run your commands as normal. # adds a note, ## starts a section.

$ runscribe record
* recording - commands run for real; # note, ## section, exit to finish
runscribe:api$ ## Deploy the API
runscribe:api$ # bump the release tag first
runscribe:api$ git tag v2.3.0
runscribe:api$ export DEPLOY_TOKEN=ghp_R2d9nQx7b4Kp...A1
runscribe:api$ ./deploy.sh production
runscribe:api$ exit
recorded 3 commands -> .runscribe/sessions/20260710.jsonl
Enter fullscreen mode Exit fullscreen mode

2. Build — turn the session into a runbook, with secrets scrubbed automatically.

$ runscribe build --last -o deploy.md
done 3 commands (1 redacted) -> deploy.md
Enter fullscreen mode Exit fullscreen mode

You get clean Markdown: sections become headings, notes become prose, and each command is a fenced block tagged with a marker so it can be replayed later. That DEPLOY_TOKEN shows up as <REDACTED>.

3. Run — replay the runbook step by step, later or on another machine.

$ runscribe run deploy.md
running 2 step(s) from deploy.md
value for {{ENV}}: production
## Deploy the API
$ git tag v2.3.0
  run this step? [Y]es / [s]kip / [q]uit: y
$ ./deploy.sh production
  run this step? [Y]es / [s]kip / [q]uit: y
done  ran 2, skipped 0, failed 0
Enter fullscreen mode Exit fullscreen mode

Every command is shown before it runs, {{PLACEHOLDER}} tokens get filled in (prompted, or via --set NAME=value), and a failing step halts the run unless you pass --keep-going.

Export to HTML if you'd rather share a page than a Markdown file:

runscribe build --last --format html -o deploy.html
Enter fullscreen mode Exit fullscreen mode

A single self-contained file, styles inlined, everything HTML-escaped.

A few things under the hood

  • Deterministic redaction. A regex ruleset scrubs common tokens, keys, and credentials, and you can extend it with a .runscribe/redact.toml (extra patterns and literal strings). No ML, no guessing.
  • State that persists. On POSIX, recording drives a single long-lived shell via a sentinel technique, so cd, export, and shell variables carry across steps just like a real session. There's an opt-in --pty mode for colored output and simple TUIs.
  • No INTERNET anywhere. There's no networking code in the project. That's the point — your shell history never leaves the machine.
  • Ships as a binary too. PyInstaller builds a one-file executable for Linux, macOS, and Windows, so a teammate without Python can still use it.

Why no AI?

Plenty of tools will "write your docs" now, but they do it by shipping your shell activity off to a model. If you've ever hesitated before pasting internal commands into a chatbot, that hesitation is the whole reason runscribe exists. A runbook is deterministic by nature: it should come out the same every time, and it should never require trusting a third party with what you typed.

Try it 

pip install runscribe
Enter fullscreen mode Exit fullscreen mode

It's open source and still early. If you write runbooks (or avoid writing them), I'd genuinely love feedback — and if you try it and something feels rough, open an issue. That's the most useful thing right now.

Top comments (1)

Collapse
 
topstar_ai profile image
Luis •

Great idea. Turning terminal history into reusable runbooks solves a very real developer pain point — many valuable operational workflows exist only in someone’s shell history or memory.

I especially like the offline-first approach. For infrastructure, security, and internal tooling, keeping sensitive commands and operational knowledge local can be a major advantage.

The next interesting layer would be adding structure around these generated runbooks: tagging, validation steps, environment notes, and sharing workflows for teams. Capturing tribal knowledge and turning it into repeatable processes is a huge productivity win. Great project!