bobbin

Agent-first terminal recording. Capture, replay, and share terminal sessions.

Built for AI agents and humans alike — every command supports --json for machine-readable output.

Install

npm install -g @bobbin/cli

Or run directly with npx:

npx @bobbin/cli rec

For PTY-based recording (better fidelity), also install the optional dependency:

npm install -g node-pty

If node-pty is not available, bobbin falls back to the Unix script command automatically.

Quick start

# Record an interactive session
bobbin rec

# Record a specific command
bobbin rec -- npm test

# Play it back
bobbin play ~/.config/bobbin/recordings/bobbin-1709472000000.cast

# Play a shared recording by URL or ID
bobbin play https://bobbin.work/r/P2fumq1n
bobbin play bobbin.work/r/P2fumq1n
bobbin play P2fumq1n

# Upload and share
bobbin upload ~/.config/bobbin/recordings/bobbin-1709472000000.cast

# List your recordings
bobbin ls

Commands

bobbin rec [command...]

Record a terminal session. Without a command, starts an interactive shell — type exit to stop.

bobbin rec                          # interactive session
bobbin rec -- make build            # record a specific command
bobbin rec -o my-session.cast       # custom output path
bobbin rec -t "deploy fix" -- ./deploy.sh

| Flag | Description | |------|-------------| | -o, --output <file> | Output file path (default: ~/.config/bobbin/recordings/bobbin-<timestamp>.cast) | | -t, --title <title> | Recording title stored in metadata | | --json | JSON output for agent consumption |

Recordings are saved in asciicast v2 format with additional bobbin metadata including git context (branch, SHA, repo).

bobbin play <file | url | id>

Play back a recording in the terminal with real timing. Accepts a local file, a bobbin.work URL, or a bare recording ID.

# Local file
bobbin play session.cast
bobbin play session.cast -s 3       # 3x speed

# Remote — all equivalent
bobbin play P2fumq1n
bobbin play bobbin.work/r/P2fumq1n
bobbin play https://bobbin.work/r/P2fumq1n

When given a URL or ID, bobbin fetches the recording from the server, plays it, and cleans up the temporary file automatically.

| Flag | Description | |------|-------------| | -s, --speed <n> | Playback speed multiplier (default: 1) | | --server <url> | Server URL for remote playback (default: https://bobbin.work) | | --json | JSON output |

bobbin upload <file>

Upload a recording to a bobbin server and get a shareable URL.

bobbin upload session.cast
bobbin upload session.cast -t "CI failure repro"
bobbin upload session.cast --server https://my-server.com

| Flag | Description | |------|-------------| | -t, --title <title> | Title for the shared recording | | --server <url> | Server URL (default: https://bobbin.work or BOBBIN_SERVER env var) | | --json | JSON output |

Returns a shareable URL and a management URL. The management key is saved locally to ~/.config/bobbin/uploads.json.

bobbin download <id | url>

Download a recording from a bobbin server.

bobbin download P2fumq1n
bobbin download https://bobbin.work/r/P2fumq1n
bobbin download P2fumq1n -o recording.cast

| Flag | Description | |------|-------------| | -o, --output <file> | Output file path (default: <id>.cast in current directory) | | --server <url> | Server URL | | --json | JSON output |

bobbin ls

List recordings.

bobbin ls               # local recordings
bobbin ls --remote      # uploaded recordings

| Flag | Description | |------|-------------| | --remote | List uploaded recordings instead of local ones | | --json | JSON output |

Agent usage

Every command supports --json for structured output. Info messages go to stderr, data goes to stdout as JSON.

# Record and capture result
result=$(bobbin rec --json -- npm test)
echo "$result" | jq '.duration'

# Upload and get URL
url=$(bobbin upload --json session.cast | jq -r '.url')

# Play a shared recording
bobbin play P2fumq1n

# List recordings as JSON array
bobbin ls --json | jq '.[].file'

Agent integration example

An AI agent can record its own terminal sessions and share them:

# Agent records a debugging session
bobbin rec --json -t "investigating OOM" -- ./debug.sh
# => {"status":"complete","file":"/home/user/.config/bobbin/recordings/bobbin-1709472000000.cast","duration":12.3,"exitCode":0}

# Agent uploads and gets a shareable link
bobbin upload --json /home/user/.config/bobbin/recordings/bobbin-1709472000000.cast
# => {"url":"https://bobbin.work/r/P2fumq1n","manage":"https://bobbin.work/r/P2fumq1n?key=...","id":"P2fumq1n"}

# Another agent or human plays it back
bobbin play P2fumq1n

Configuration

| Item | Location | |------|----------| | Recordings | ~/.config/bobbin/recordings/ | | Upload metadata | ~/.config/bobbin/uploads.json |

Environment variables

| Variable | Description | |----------|-------------| | BOBBIN_SERVER | Default server URL (overrides https://bobbin.work) | | SHELL | Shell used for interactive recording (default: /bin/bash) |

Recording format

Bobbin uses asciicast v2 with an extended header:

{
  "version": 2,
  "width": 120,
  "height": 40,
  "timestamp": 1709472000,
  "bobbin": {
    "version": "0.1.0",
    "command": "npm test",
    "git_repo": "user/project",
    "git_branch": "main",
    "git_sha": "a1b2c3d"
  }
}

Recordings are compatible with asciinema and any tool that reads asciicast v2.

Recording backends

Bobbin supports two recording backends:

| Backend | When used | Fidelity | |---------|-----------|----------| | PTY (node-pty) | When node-pty is installed | Full terminal emulation — colors, cursor movement, resize events | | script | Fallback when node-pty is unavailable | Uses the Unix script command — good enough for most use cases |

The backend is detected automatically. No configuration needed.

Security

Automatic credential redaction

Bobbin automatically redacts common credential patterns from recordings before they're written to disk:

• Management keys in URLs (?key=...)
• JSON key/secret fields
• Environment variable patterns (TOKEN=..., SECRET=..., PASSWORD=..., API_KEY=...)
• AWS access keys (AKIA...)
• Bearer tokens
• GitHub tokens (ghp_, gho_, ghs_, github_pat_)
• Basic auth in URLs (https://user:pass@host)
• Private key blocks (-----BEGIN PRIVATE KEY-----)
• Database connection strings with passwords

Redaction is best-effort. Always review recordings before sharing, especially if your session involved credentials, API keys, or private data.

File permissions

All files bobbin creates are locked down:

| Path | Mode | Description | |------|------|-------------| | ~/.config/bobbin/ | 0700 | Config directory — owner only | | ~/.config/bobbin/recordings/*.cast | 0600 | Recording files — owner read/write only | | ~/.config/bobbin/uploads.json | 0600 | Upload metadata with management keys | | Temporary files during playback | 0600 | Cleaned up after use |

What gets recorded

A recording captures all terminal output from the session. This may include:

• Command output and error messages
• File contents displayed with cat, less, etc.
• Environment variables if printed
• Anything visible in the terminal

It does not capture stdin (keystrokes) — only the output side.

What does NOT go into recordings

• Your current working directory
• Your environment variables (beyond what appears in terminal output)
• Files outside the terminal session

Download/playback limits

Remote recordings are capped at 10 MB to prevent abuse. Both the download and play commands enforce this limit.

Server validation

All commands that contact a server validate the URL scheme (https:// or http://). HTTP connections produce a warning. The server URL cannot be manipulated via recording IDs — IDs are sanitized to [a-zA-Z0-9_-] only.

Requirements

• Node.js 18+
• Linux or macOS
• Optional: node-pty for higher-fidelity recording