{
"markdown": "# vibe-replay\n\n[](https://www.npmjs.com/package/vibe-replay)\n[](https://www.npmjs.com/package/vibe-replay)\n[](./LICENSE)\n\nTurn Claude, Cursor, Codex, OpenCode, Hermes, Pi, and Grok Bot sessions into shareable, interactive replays — then analyze them with local insights, AI Studio, and Ask Replay.\n\n### The problem\n\nAI agents write code in long, complex sessions — dozens of tool calls, hundreds of file edits, thousands of lines of reasoning. When the session ends, all that context disappears. Your PR diff shows _what_ changed, but reviewers can't see _why_. Teammates can't learn from your prompting. You can't even replay your own session next week.\n\n### The fix\n\nOne command. One self-contained HTML file. Every prompt, every thought, every tool call — animated, searchable, and ready to share.\n\n```bash\nnpx vibe-replay\n```\n\n> Also available as a [Claude Code plugin](#claude-code-plugin) — your agent generates replays automatically during PR creation.\n\n> **[Watch a live demo →](https://vibe-replay.com/view/?gist=c40137e4c224dc883fe2eaa668e2d8ba)**\n\n
\n \n
\n\n\n## What You Get\n\n### All your sessions, one place\n\nLaunch with `npx vibe-replay -d` and see every Claude, Cursor, Codex, OpenCode, Hermes, Pi, and Grok Bot session across all projects — with a daily activity snapshot, activity heatmaps, cost totals, and project analytics. Search sessions, filter by git repo, tool, MCP server/tool, skill, or context compaction, expand any session to see its own tool/MCP breakdown, and generate any replay in one click.\n\n
\n \n
\n\n### Remote SSH sources\n\nThe dashboard can also include JSONL sessions from any OpenSSH-compatible host. Add targets from the\ndashboard's **Settings** tab, or directly in `~/.vibe-replay/config.json`:\n\n```json\n{\n \"remoteSources\": [\n {\n \"id\": \"remote-dev\",\n \"label\": \"Remote dev\",\n \"sshHost\": \"devbox\",\n \"providers\": [\"codex\", \"claude-code\", \"pi\"]\n }\n ]\n}\n```\n\nThe Settings form validates source ids, provider selections, and connection timeouts, and can run a\nbounded SSH probe before you refresh the catalog. It uses your existing OpenSSH keys, aliases, and\nProxyJump configuration; credentials are never stored by vibe-replay.\n\n`sshHost` can be a normal hostname or an alias from `~/.ssh/config`, so existing keys, agents, `ProxyJump`, and `ProxyCommand` configuration continue to work. No private key or password belongs in this file. Remote Codex, Claude Code, and Pi JSONL files are copied into a per-target local cache and parsed by the same providers as local sessions; source cards show the configured location label. A transcript that is still being written is kept at its last stable cached version instead of making the whole SSH source unavailable. Codex titles match `/resume`: explicit names from `session_index.jsonl` take precedence over the read-only `state_5.sqlite` title. The live database and WAL are never copied. Hosts with Python `sqlite3` or the `sqlite3` CLI unavailable still use cached metadata. Sessions whose source is missing, unreadable, or contains no meaningful human prompt remain visible with an explicit status and cannot be generated into an empty replay. Remote repository identity is retained for local filtering but omitted from shareable replay data. Remote Live mode is intentionally unavailable. Remote sessions stay in local insights and are excluded from optional cloud insight sync.\n\n### Watch the full replay\n\nPick a session and step through every prompt, thinking block, tool call, and code diff with animated playback. Three view modes — All, Compact, and Custom.\n\n
\n\n### Deep insights for every session\n\nAuto-generated analytics: token burn & cost over time, context window usage, cache read share, tool call distribution, model breakdown, and per-turn breakdowns.\n\n
\n \n
\n\nThe Insights **Coverage** section separates scan completion from metric availability and shows\nprovider-level precision for invocations, MCP calls, tokens, cache reads/writes, and compactions.\n“Uncached / miss” is a derived prompt metric (`uncached input + cache writes`); providers do not\nshare one universal cache-miss counter. Cursor snapshot totals are marked estimated, and Cursor\ncompactions are lower bounds because its local store can retain only the latest summary.\n\nWhen providers persist context-composition metadata, a replay's Insights view also breaks out the\nsystem prompt, tool definitions, rules, skills, MCP definitions, subagents, summaries, and\nconversation. Cursor supplies provider-estimated tokens for its latest snapshot; Cowork, Codex,\nand Pi expose privacy-safe byte/count aggregates from persisted metadata. Raw system prompts, tool\ndescriptions, and schemas are never copied into this breakdown.\n\n### Your AI coding wrapped\n\nGitHub-style activity heatmap, streaks, weekly trends, top projects, model usage, and cost tracking across all your sessions. See how your coding patterns evolve over time.\n\nThe aggregate Insights dashboard also shows per-session percentile distributions for duration, tool calls, turns, and tokens, plus per-turn distributions for duration, tool calls, and tokens.\n\n
\n \n
\n\n### AI Studio and Ask Replay\n\nGo beyond playback without sending your session history to a hosted service. **AI Studio** uses the\nembedded Pi runtime to analyze a replay, translate it, or adjust its tone with the provider you\nchoose — including OpenAI-compatible endpoints and local gateways. **Ask Replay** is a read-only\nassistant for searching sessions, explaining usage and Insights, inspecting scenes and overlays, and\njumping to stable dashboard or replay links. It never edits files, publishes, or mutates data on its\nown; any requested action is handed back to you for review.\n\n## Claude Code Plugin\n\nvibe-replay is also available as a [Claude Code plugin](https://code.claude.com/docs/en/plugins). Once installed, your agent learns how to generate replays autonomously — it can find the current session, produce GitHub-ready artifacts, and embed them in PRs, all without you running any CLI commands.\n\n### What the plugin gives your agent\n\n- **Auto-discover sessions** — finds the current session's JSONL file via `$CLAUDE_SESSION_ID`\n- **Search past sessions** — uses `vibe-replay sessions` to find Claude, Cursor, Codex, OpenCode, Hermes, and Pi sessions by project, provider, or fuzzy query\n- **Generate PR artifacts** — markdown summary + animated GIF + SVG, ready for PR descriptions\n- **Generate HTML replays** — self-contained interactive replay files\n- **PR workflow integration** — agent automatically embeds replay context when you create PRs\n\n### Pseudonymous CLI telemetry\n\nThe CLI sends opt-out, pseudonymous feature counts and coarse scan-size buckets\nto improve the product. It never sends prompts, replay/session contents, paths,\nproject names, or user IDs. Disable it with `vibe-replay telemetry disable`,\n`VIBE_REPLAY_TELEMETRY=0`, or `DO_NOT_TRACK=1`; CI runs disable it automatically.\n\n### Install (recommended)\n\nOpen Claude Code, run `/plugin`, then search **vibe-replay** in the **Discover** tab and install.\n\nOr install via CLI:\n\n```bash\n/plugin marketplace add tuo-lei/vibe-replay\n/plugin install vibe-replay@vibe-replay\n```\n\n### Agent Skills install (Cursor, Codex, and others)\n\nvibe-replay also ships a portable `SKILL.md` under `skills/replay/`, so agents that support the Agent Skills standard can install the same replay workflow without the Claude plugin marketplace.\n\n```bash\nnpx skills add tuo-lei/vibe-replay --skill replay -g\n```\n\nThis installs the `replay` skill globally through the Agent Skills CLI. Cursor discovers global skills from `~/.agents/skills/` and `~/.cursor/skills/`, so this is the recommended install path for Cursor users.\n\n### Manual install (single file)\n\nIf you prefer not to install through a marketplace or the Agent Skills CLI:\n\n```bash\nmkdir -p ~/.claude/skills/replay\ncurl -o ~/.claude/skills/replay/SKILL.md \\\n https://raw.githubusercontent.com/tuo-lei/vibe-replay/main/skills/replay/SKILL.md\n```\n\n### Usage examples\n\n```\n# Slash command — generate a replay of the current session\n/vibe-replay:replay\n\n# Natural language — agent auto-triggers during PR creation\n\"Create a PR with session replay\"\n\"Create a PR for this change, include an animated GIF of the session\"\n\n# Direct replay\n\"Generate an interactive replay of this session and open it\"\n```\n\n## Features\n\n- **Local-first** — one command and no account required for local replays; sign in only when you want cloud publishing or synced insights\n- **Cross-platform** — runs on macOS, Linux, and Windows\n- **Single HTML file** — self-contained, works offline, and makes no automatic external requests. Remote image attachments load only after an explicit click\n- **Claude, Cursor, Codex, OpenCode, Hermes, Pi, and Grok Bot** — all providers auto-discovered, including multi-file and resumed sessions\n- **Remote SSH sources** — optionally combine remote Codex, Claude Code, and Pi JSONL sessions with local sessions using standard OpenSSH configuration\n- **Local dashboard** — browse and search every session, filter by git repo, tool, MCP server/tool, skill, or context compaction, expand a session for its own tool/MCP/skill counts, with activity heatmaps, per-project analytics, and a personal-insights view (including which tools and MCP servers you lean on) across all your coding\n- **AI Studio** — use the embedded Pi runtime to analyze, translate, and professionalize replays with your selected provider/model, including OpenAI-compatible local or remote endpoints\n- **Ask Replay** — ask read-only questions about sessions, scenes, annotations, overlays, usage, coverage, projects, and Insights; get stable permalinks instead of opaque chat answers\n- **Share & export** — GitHub Gist, animated SVG, GIF, markdown summary, or cloud upload. Secret redaction built in\n- **Sub-agent visualization** — see delegated tool calls and sub-agent trees rendered inline\n- **Comments** — leave notes on any scene. Comments persist in the HTML and travel with the replay\n- **Live mode** — `vibe-replay live` follows a running local session as new turns land on disk; SSH-backed live mode is intentionally disabled\n\n## Supported Providers\n\n| Provider | Status |\n|----------|--------|\n| Claude Code | Supported |\n| Claude Desktop | Supported |\n| Claude Cowork | Supported (agent-mode sessions) |\n| Codex | Supported (web search, GPT-5.x models, task timings, memory mode) |\n| Cursor | Supported (SQLite + JSONL + SDK store, auto-discovered) |\n| OpenCode | Supported (SQLite sessions, tools, reasoning, and compaction) |\n| Hermes | Supported (SQLite sessions, tools, reasoning, and compaction) |\n| Pi | Supported (JSONL tree sessions, branching, compaction summaries) |\n| Grok Bot | Supported (cloud-box JSONL; `send_message` promoted to visible replies; group-chat wakes split per speaker) |\n| More coming soon | — |\n\nGrok Bot sessions live on the cloud box (`/home/box/agent-data/agent-transcripts`, often a symlink to `sand-data`). Point discovery at a copy with `GROK_BOT_TRANSCRIPTS_DIR` (or `VIBE_REPLAY_GROK_BOT_DIR`), or drop files under `~/.grok-bot/agent-transcripts`. Group-chat user lines starting with `[Group chat:` become a room context-injection plus one user turn per `Speaker: message`; Eng and GTM keep separate transcripts:\n\n```bash\nGROK_BOT_TRANSCRIPTS_DIR=/path/to/agent-transcripts npx vibe-replay -p grok-bot\n```\n\nSSH remote indexing of Grok Bot transcripts is not included yet.\n\n## How It Works\n\n```\nAI session files → vibe-replay → self-contained HTML\n(Claude/Cursor, (discover, (animated viewer,\n Codex/OpenCode, parse, insights panel,\n Hermes/Pi/Grok Bot) redact, offline-ready,\n transform) shareable)\n```\n\nThe CLI auto-discovers sessions on your machine, parses conversation data from all sources, and packages everything into a pre-built React viewer — one HTML file that works anywhere.\n\n**After generation:**\n- **Open in Editor** — annotate scenes, get AI feedback, export to multiple formats\n- **AI Studio** — configure Pi once from the global Settings page or the reusable Manage Providers\n dialog in AI Studio, then analyze, translate, or professionalize sessions with\n OpenAI, ChatGPT/Codex subscription, OpenRouter, or OpenCode Zen. No Claude, OpenCode, or other\n headless CLI is required. You can also add an OpenAI-compatible proxy (including LiteLLM) in\n the editor; AI Studio discovers models from its `/models` endpoint and sends Chat Completions\n requests to the configured local or remote API root.\n- **Ask Replay** — ask read-only questions about local sessions, replay scenes, comments, AI Studio\n overlays, usage, coverage, projects, and Insights ranges from the Dashboard or Editor. It mirrors\n the explorer's provider/repository/tool/MCP/skill/compaction filters and returns stable permalinks\n for resources and user-reviewed mutation handoffs; it never performs a mutation itself. SSH-backed\n data stays hidden unless you enable it in Settings. The setting is browser-local and can be changed\n at any time.\n- **Quick preview** — open in browser instantly\n- **Publish to Gist** — shareable link on [vibe-replay.com](https://vibe-replay.com)\n- **Export for GitHub** — markdown + animated SVG for PRs\n\n## Use Cases\n\n- **Vibe coding review** — replay your AI-assisted coding sessions to spot prompting patterns and improve your workflow\n- **Team knowledge sharing** — show teammates _how_ you built something, not just the final diff\n- **PR context** — attach a replay link to PRs so reviewers understand the reasoning behind changes\n- **Teaching & onboarding** — create replayable walkthroughs of real coding sessions for documentation or training\n- **Cost tracking** — see exactly how many tokens each session burns, track costs across projects\n\n## Security & Privacy\n\n- **Self-contained HTML** — generated replay files embed viewer assets inline and make no automatic external requests when opened from disk. Remote image URLs are blocked until you explicitly choose to load an individual image. (Gist/cloud-backed replays fetch data from GitHub or the vibe-replay API on load.)\n- **Secret redaction** — API keys, tokens, PEM keys, and sensitive paths are automatically detected and redacted before generation\n- **Local by default** — vibe-replay reads session files from your machine and generates a local HTML file. Data only leaves your machine when you explicitly publish (Gist or cloud upload), or if you log in — in which case aggregated local session insights (counts, durations, costs — no conversation content) sync daily to the cloud. Remote SSH session aggregates stay local.\n- **Local AI setup** — AI Studio and Ask Replay use the embedded Pi provider and agent runtime.\n Credentials stay outside replay files and cloud uploads; AI requests only run after a configured\n provider and usable model are selected. When Pi's `settings.json` defines a default provider/model,\n Vibe Replay honors it only when the provider identity (provider id or configured endpoint) and exact\n model are both verified; it never silently chooses the first catalog entry. Provider keys and OAuth refresh tokens are stored in\n `~/.vibe-replay/ai-auth.json` with restricted permissions (`VIBE_REPLAY_AI_AUTH` can override the path).\n Custom endpoint metadata is stored separately in `~/.vibe-replay/ai-providers.json` with the\n same local-only permissions; the endpoint file never contains the custom API key. Enter a base\n URL such as `http://127.0.0.1:58788/v1` in Settings or the AI Studio provider dialog, not\n `/models` or `/chat/completions`. HTTP is restricted to loopback endpoints; use HTTPS for a\n remote gateway. The selected provider/model is remembered automatically as a browser-local\n preference; model lists are searchable rather than hardcoded.\n\n## Development\n\n```bash\ngit clone https://github.com/tuo-lei/vibe-replay.git\ncd vibe-replay\npnpm install\npnpm dev # Viewer (Vite HMR) + CLI (auto-restart) — full HMR\npnpm dev:website # Website (Astro HMR) + Viewer (Vite HMR)\n```\n\nThe dev launchers reserve their selected ports for the lifetime of the\nlauncher, so multiple worktrees can start at the same time without selecting\nthe same port during startup. To choose a fixed pair explicitly, use\n`VIBE_API_PORT` and `VIBE_VIEWER_PORT`:\n\n```bash\nVIBE_API_PORT=13457 VIBE_VIEWER_PORT=5174 pnpm dev\nVIBE_VIEWER_PORT=5175 VIBE_WEBSITE_PORT=4322 pnpm dev:website\n```\n\nThe requested ports must be free and different within the same launcher. If\nonly one port is overridden, automatic selection skips that port as well.\n\nCLI usage requires Node.js >= 22.19.0. The `website` package uses Astro 7 and\nrequires Node.js >= 22.12.0. Its scripts use a cross-platform Node launcher\nthat searches standard nvm-managed installations when needed. If a global\npackage-manager shim selects an older Node for child commands, verify\n`corepack pnpm exec node -v` and use `corepack pnpm ...` after selecting a\ncompatible Node version; see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for architecture details and development workflow.\n\nContributing with a coding agent? Project instructions live in\n[AGENTS.md](./AGENTS.md), which Claude Code, Codex, Cursor, Pi, and opencode all\nread. See [Working with a coding agent](./CONTRIBUTING.md#working-with-a-coding-agent).\n\n## License\n\n[MIT](./LICENSE)\n",
"bytes": 18430,
"sha": "2306511c246d2e1a15b6716327fde21c379fc8e29d31d23df7bedd9a8915da05",
"repo_slug": "tuo-lei/vibe-replay",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_tuo_lei_vibe_replay_vibe_replay_f0e07a1b/readme"
}
![\"vibe-replay](\"docs/screenshots/product-demo.gif\")
\n![\"Local](\"docs/screenshots/dashboard.png\")
\n![\"Animated](\"docs/screenshots/compact-mode.png\")
\n \n![\"Session](\"docs/screenshots/insights.png\")
\n![\"Personal](\"docs/screenshots/personal-insights.png\")
\n