Shell history to runbook generator

The idea

A command-line tool that reads your shell history file, clusters sequences of commands that tend to run together (deploy steps, DB migration checks, log-pulling incantations, that one kubectl dance you always forget), and proposes them back to you as named, parameterized runbooks. You confirm or edit the cluster, give it a name, and it's saved as a documented shell script with placeholders for the parts that change (branch names, pod names, dates). Run it later with rb run deploy-staging instead of grepping your own history at 2am trying to remember the flag order.

Why build this

Every engineer has a personal graveyard of half-remembered command incantations buried in .zsh_history — the exact rsync flags that worked, the psql one-liner that checks replication lag, the three-command sequence to roll back a bad deploy. None of it is written down because writing runbooks feels like a separate chore from doing the work. This tool flips that: the runbook writes itself from what you already typed. It's especially useful for small teams without a dedicated platform engineer, where tribal knowledge lives in individual histories instead of a wiki, and onboarding a new hire means shoulder-surfing a senior dev's terminal for a week.

Stack sketch

• CLI in Go or Rust for fast startup and single-binary distribution (rb command)
• Local SQLite store for detected command clusters, confirmed runbooks, and run history
• Sequence clustering via a simple sliding-window n-gram approach first (exact/near-exact repeated subsequences within a time gap threshold) — no ML needed for v1
• Shell integration via a lightweight hook (precmd/PROMPT_COMMAND) to capture command + exit code + cwd, or a one-shot parse of existing history files as a fallback
• Parameter detection with regex heuristics (dates, UUIDs, branch-like strings, IP addresses) prompting the user to confirm which tokens should become {{placeholders}}
• Optional Markdown export so runbooks can live in a repo's runbooks/ folder and get reviewed like code

Scope for v1

• In: parse existing shell history, surface top N repeated sequences ranked by frequency and recency, interactive confirm/name/edit flow, save as runnable parameterized scripts, rb run <name> and rb list
• In: manual rb save to hand-capture a sequence you just ran, for cases the clustering misses
• Out: live daemon/hook-based capture (ship the history-file parser first, add the hook later)
• Out: team sync or sharing — v1 is single-machine, local-only
• Out: cross-shell support beyond bash/zsh (fish, PowerShell come later)

Where it could go

The natural next step is a shared team layer: a lightweight sync (git-backed, or a small self-hosted server) so runbooks generated by one engineer get suggested to teammates who show similar command patterns — turning individual muscle memory into a shared library without anyone sitting down to "write documentation." From there, integrating with incident tooling is an easy win: link a runbook to a PagerDuty alert type so the on-call engineer gets rb run rollback-payments-service suggested directly in the incident channel instead of having to remember it exists.

A second direction is safety rails — dry-run mode that shows exactly what a runbook will execute before it runs, with diffing against the current environment (is this branch still valid, does this pod still exist) so stale runbooks fail loudly instead of running a command against something that no longer matches the assumptions baked into it.

Watch out for

Naive sequence clustering will find plenty of noise — cd, ls, git status chains that aren't really a "runbook," just normal browsing. Spend real effort on the ranking and filtering heuristics (minimum sequence length, requiring at least one non-trivial command, weighting by how often the exact sequence recurs across sessions) or the tool will bury useful clusters under garbage and users will stop trusting its suggestions.