TermSnapshot

Record terminal sessions as shareable JSON — replay anywhere, no vendor lock-in

TermSnapshot records your terminal sessions into plain JSON files. No proprietary format, no account, no player to install. Share a .termsnapshot.json file and anyone can replay it in seconds.

# Install
npm install -g termsnapshot

# Record a session
termsnapshot record -o my-session.termsnapshot.json

# Replay in terminal
termsnapshot play my-session.termsnapshot.json

# Export to a standalone HTML page (open in any browser)
termsnapshot export my-session.termsnapshot.json -o replay.html

Why TermSnapshot?

| | TermSnapshot | asciinema | |---|---|---| | File format | Plain JSON | .cast (binary-ish) | | Replay without tool | ❌ — needs asciinema player | ❌ — needs asciinema player | | Export to HTML | ✅ Native | ❌ No | | Browser replay | ✅ Any browser, self-contained HTML | ❌ No | | Git-friendly | ✅ Yes | ⚠️ Large files | | No account needed | ✅ Yes | ❌ Requires asciinema.org |

Features

• Record — Spawns a real PTY and captures all output + input with precise timestamps
• Replay — Plays back session in your terminal with configurable speed
• Export — Generates a fully self-contained HTML page with an interactive player
• Inspect — info command shows session metadata without playing
• Plain JSON — Session files are just JSON. Parse them anywhere. Build your own tooling.

Installation

Via npm (recommended)

npm install -g termsnapshot

Via npx (no install)

npx termsnapshot record -o demo.termsnapshot.json

From source

git clone https://github.com/YOUR_USERNAME/termsnapshot.git
cd termsnapshot
npm install
npm run build
npm link

Quick Start

# Record
termsnapshot record -o demo.termsnapshot.json

# Replay
termsnapshot play demo.termsnapshot.json --speed 2.0

# Export HTML
termsnapshot export demo.termsnapshot.json -o demo.html

# Inspect
termsnapshot info demo.termsnapshot.json

Session File Format

Session files are plain JSON:

{
  "version": "1.0.0",
  "title": "Deploying my app",
  "createdAt": "2026-04-10T00:00:00.000Z",
  "shell": "bash",
  "terminal": { "cols": 80, "rows": 24 },
  "events": [
    { "type": "output", "ts": 0,    "data": "user@host:~$ " },
    { "type": "input",  "ts": 120,  "data": "git push\n" },
    { "type": "output", "ts": 135,  "data": "Enumerating objects: 100%\n" }
  ],
  "exitCode": 0,
  "duration": 5420
}

Event types:

• output — Terminal output (stdout + stderr)
• input — User keyboard input
• resize — Terminal resize events
• info — Metadata events (cwd, env, etc.)

HTML Export

The exported HTML file is fully self-contained — no external dependencies, no CDN, no tracking. It embeds:

• ANSI escape sequence rendering (colors, bold, etc.)
• Interactive playback controls (play, pause, reset)
• Scrub-able progress bar
• Auto-play on load
• Dark/light theme support

Open the HTML file directly in any browser. Share it anywhere.

CLI Reference

termsnapshot <command> [options]

Commands:
  record           Start recording a new terminal session
  play <file>      Replay a session from a JSON file
  export <file>    Export a session to a standalone HTML page
  info <file>       Show info about a session file
  (default)        Start recording (shorthand for `record`)

Global Options:
  -h, --help       Show help
  -v, --version    Show version

Record Options:
  -o, --output <path>   Output file path  (default: session.termsnapshot.json)
  -t, --title <title>   Session title      (default: Untitled Session)
  -s, --shell <shell>   Shell to spawn     (default: bash)

Play Options:
  -s, --speed <scale>   Playback speed multiplier (default: 1.0)

Export Options:
  -o, --output <path>   Output HTML path  (default: session_replay.html)
  -t, --title <title>   Page title         (default: TermSnapshot Replay)

Architecture

src/
  cli.ts            # Commander.js entry point
  commands/
    record.ts       # PTY recording logic
    play.ts         # Terminal replay
    export.ts       # HTML export
    info.ts         # Session info
  lib/
    pty.ts          # node-pty wrapper (PtyRecorder)
    session.ts      # Session type definitions
    renderer.ts     # HTML renderer for exports
    version.ts      # Version constant

Building

npm install
npm run build     # TypeScript → dist/
npm test          # Run test suite

Contributing

Contributions are welcome! Please open an issue first to discuss any non-trivial changes.

License

MIT © 2026