터미널 기록을 런북으로 변환하는 오프라인, no-AI 도구를 만들었습니다.

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

• PyPI: https://pypi.org/project/runscribe/
• Code + demo: https://github.com/hamzamansoorch/runscribe
• License: MIT

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.