⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
session-story
Generate a self-contained HTML "session story" that links each prompt in a vibe coding session to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative. Use when the user asks for a session recap, changelog, review artifact, "what did Claude change", or wants to share a summary of a Claude Code session with a teammate or stakeholder.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Session Story
Generate a self-contained HTML "session story" that links each prompt in a vibe coding session to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative.
Session Story is a zero-dependency Node.js extraction and rendering pipeline for Claude Code. It parses the session transcript into typed JSON IR, cross-indexes prompts to the edits they caused, and deterministically compiles that into one HTML file with inline CSS and JS.
- Open it and review — a GitHub-style diff, a turn-by-turn timeline, a plain-language narrative, and a report of what happened (commands, tests, errors, decisions, outcome), switchable in one page
- Reconstruct intent, not just diffs — every edit is linked back to the prompt and turn that produced it, in order
- Honest about blind spots — an interrupted tool call or a change made by a shell command is called out in the page header instead of silently omitted
- One file, ready to share — no server, no build step, works straight from
file://
Git tells you what changed. This tells you what happened.
Start page · Live example. The example is built from a synthetic demo session; the same page is checked in at examples/story.html.
Quick start
1. Install
The installer needs Node.js 22.20+ (check with node -v). For all your projects:
npx -y skills add nalaj/session-story --skill session-story --agent claude-code --global --copy --yes
For the current repository only, drop --global:
npx -y skills add nalaj/session-story --skill session-story --agent claude-code --copy --yes
This uses the open skills CLI. It copies only the session-story/ folder (the skill's instructions) into your agent's skills directory. When the skill runs, it fetches the matching version of the session-story CLI from npm through npx. The installer needs Node.js 22.20+ (the skills CLI's own requirement); the CLI runs on Node.js 18.18+ with zero npm runtime dependencies. To update, run the same command again. To remove it: npx skills remove session-story.
On older Node, this fetches Node 22 for the install only and changes nothing else (tested on macOS; for a lasting fix, upgrade Node, e.g. nvm install 22):
npx -y -p node@22 -p skills -- skills add nalaj/session-story --skill session-story --agent claude-code --global --copy --yes
As a Claude Code plugin. This repository is also a plugin marketplace. Inside Claude Code, run:
/plugin marketplace add nalaj/session-story
/plugin install session-story@session-story
On Claude Code 2.1.275 or later, one line does both: /plugin install session-story --marketplace nalaj/session-story. Claude Code installs only the session-story/ folder; the skill fetches the CLI with npx when it runs. As a plugin, the skill's command is /session-story:session-story. To update, run /plugin marketplace update session-story.
Or run the CLI yourself with npx session-story, or from a clone with node cli/bin/story.mjs.
2. Generate a story
Inside Claude Code, once installed:
/session-story
Or just ask: "make a story of this session for my teammate".
Claude extracts the current session, writes one-sentence summaries per turn, and opens the rendered page. See session-story/SKILL.md for the exact flow.
Older sessions work too. The story is built from the transcript Claude Code keeps on disk, not from the model's context, so a session from days ago is as good as the current one. Ask "make a session story for session <session-id>", or from the command line:
npx session-story extract --session <session-id> -o story.json
Session ids are the transcript file names in ~/.claude/projects/<slug>/ (the slug is the project path with / replaced by -), and /resume lists them too. Pass the full id, and --cwd <dir> when you are not in the project directory. Claude Code deletes transcripts after cleanupPeriodDays (30 by default), and edits made through the shell are recovered against today's git tree, so for an old session they can be misattributed if the files changed since.
3. Review, hand off, or share
Open the generated HTML file. Switch views depending on the audience — see below.
Need text instead of a page? export turns the same story into markdown: a
pull request description by default, or with --template handoff a status
to paste into a fresh Claude Code session (where things stand, turn by
turn, git). It prints to stdout, so it pipes straight into pbcopy or
gh pr create --body-file -.
Every session keeps its own page
Stories land in a .session-stories/ library in the project, one file per
session, named by date, session id, and a slug of the title:
.session-stories/
index.html # the gallery
index.json # the manifest it is built from
sessions.js # the sidecar the switcher reads
2026-09-14-eb076ea5-add-a-session-browser.html
2026-09-12-a91c3f02-fix-the-diff-lens.html
index.html lists every session — date, title, outcome, summary, turns,
files, lines added and removed, input and output tokens, and cost when
Claude Code recorded it — with a filter box and time period filters (today,
last 7 or 30 days, this or last calendar month, all time); the totals line
adds up whichever sessions are shown. Every story page
gets an "All sessions" link and a session switcher in its nav. Re-rendering
a session overwrites its own file rather than piling up copies.
None of that costs the single-file property. The switcher is fed by
sessions.js, loaded with <script src> (which works over file://,
unlike fetch); a story mailed on its own simply has no sidecar, so the
link and switcher stay hidden and the page is exactly as self-contained as
before. Pass --library <dir> to put the library elsewhere, or -o <file>
/ --no-library for a single standalone page and nothing else.
Choose the right view
| View | Best for | Shows
// HOW IT'S BUILT
// FILES
6 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
session-story/SKILL.md10 KB0402dde815c1upstream ↗
--- name: session-story description: Generate a self-contained HTML "session story" that links each prompt in a vibe coding session to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative. Use when the user asks for a session recap, changelog, review artifact, "what did Claude change", or wants to share a summary of a Claude Code session with a teammate or stakeholder. license: MIT metadata: version: "0.6.0" author: nalaj repository: https://github.com/nalaj/session-story --- # Session Story Turn the current (or a named) Claude Code session transcript into one shareable HTML file: git tells you what changed, this tells you what happened. The commands below run the `session-story` CLI from npm through `npx` (Node.js 18.18 or newer). The version is pinned to match this skill. Run every command from the user's project directory, so the session is found by the project's cwd. ## When to use The user asks for a session recap, a changelog of what Claude did, a review artifact for a teammate, or literally "make a story of this session" / "/session-story". ## Steps 1. **Extract.** Run the CLI to pull the session transcript (and any subagent transcripts) into a Story IR JSON file: ```bash npx -y [email protected] extract -o <scratch>/story.json --brief ``` Use `--session <id>` for a specific session or omit it (defaults to `--latest`) for the current one. Pass `--cwd <dir>` if the project differs from the current working directory. Sessions split by `/clear` are joined into one story automatically (`--no-chain` opts out), so the brief may carry turns from before the clear — `session.chain` lists the session ids included, oldest first. The `--brief` flag also prints a projection to stdout — **read only this projection, never the full story.json's hunks.** It carries, per turn: `prompt`, `edits[].{rel, kind, stats}`, `commands[].{command, category, ok, exit_code}`, `replies` (Claude's text replies, the last one longest), `errors[].{tool, target, message}`, and `plan.{approved, excerpt}` when a plan was proposed. An edit carrying `combined_into: N` is a file this turn changed through the shell whose diff git could only keep as the session's net change, shown on turn N — the turn did change code, so summarize it as a change, with zero stats rather than no edit. At the top level the brief carries `report.git` (branch and commit range, already extracted) and `report.dependencies` (manifest/install/config changes, already extracted), plus `hints` — a rough `outcome` guess from the last test/lint/build command and `failed_validations` excerpts to help you write resolutions. The brief also carries `metrics` (execution, code, validation, reads, usage — deterministic counts with `null` for anything the transcript did not record), `environment` (agent version and model ids) and, per turn, `duration_ms`, `tool_calls`, `output_tokens`, `share` (the turn's fraction of the session's output tokens, input tokens and duration, subagents included), `skills` (the skills the turn loaded) and `cache_breaks` (API calls that re-sent over 100k input tokens without the prompt cache). `metrics.execution.active_ms` is the session's time without idle gaps over five minutes; `metrics.usage` adds `cache_read_share` and `cache_breaks`. Use them to inform `report.outcome` and `outcome_note`; never restate or recompute them, and never write a number the brief shows as `null`. When one turn clearly dominated, you may say so in words ("most of the session went into the redesign"), never as a number or a cost. The same goes for skills and cache breaks: a turn summary may say "brainstormed the design first" or "re-read the whole context after a compaction", but the page already shows the names and counts. 2. **Summarize and write the report.** Using the brief projection from step 1, write directly into `<scratch>/story.json` with the Edit tool (touch nothing else in the file): - `session.title`: a short, plain-language name for the session — at most 60 characters, no trailing period. Name what the session *did* ("Session library for stories", "Fix flaky auth test"); never paste or truncate the first prompt. This is the page heading. The brief's `session.ai_title` is the harness's own name for the session — good source material, but rewrite it when it is vague or off. - `session.summary`: one or two sentences, at most 240 characters — the description under the heading, also shown in the Report lens and the library index. Lead with the outcome ("X now does Y"), name what was left out if anything, and don't restate the intent; the longer framing belongs in `report.plan`. - `turns[N].summary`: one sentence of intent per turn, in the same order as the brief output. - `turns[N].answer`: for every turn whose brief `replies` is not empty, a short summary (1-3 sentences, at most 400 characters) of what Claude answered or reported back to that prompt — the findings, the result, or the question it asked — written from `replies`. Review and Story show it as Claude's output and fold the original replies away, so it must stand on its own. Report only what the replies say; leave it out for turns with no replies. - `report.plan`: 2-4 sentences on what the session set out to do. Use any `turns[N].plan.excerpt` as source material when present. - `report.decisions`: notable technical decisions worth calling out (e.g. "used the existing service instead of a new endpoint"). Empty array if none stand out. - `report.outcome`: one of `completed`, `partial`, `failed`, `blocked` — your judgement call, informed by `hints.outcome` and whether any `errors[]` or failed commands were left unresolved. - `report.outcome_note`: optional one-liner, most useful when the outcome isn't `completed` (what it's blocked on, what's left). - `errors[N].resolution` (nested under each turn): fill in only for errors that mattered to the outcome — how it was fixed, or why it was left as-is. Leave `null` for noise (e.g. a `grep` that found nothing). 3. **Validate.** ```bash npx -y [email protected] validate <scratch>/story.json --strict ``` If this reports missing summaries or report fields, go back to step 2. 4. **Render.** ```bash npx -y [email protected] render <scratch>/story.json --open ``` This writes a self-contained HTML file (no server, no dependencies) with four switchable views — Review (timeline + a summary of Claude’s output, the original replies folded + diff, for you), Diff (file tree, GitHub-style, for a teammate), Story (narrative cards with Claude's output, for a stakeholder), Report (plan, commands, tests, errors, decisions, dependencies, git state, outcome, and the session metrics with token usage) — and opens it. The page lands in the project's `.session-stories/` library as `<date>-<session-id>-<slug>.html`, so each session keeps its own file instead of overwriting the last one, and a regenerated `.session-stories/index.html` lists every session with a search box, time period filters, and token and cost totals. Each page also gets a session switcher in its nav. Re-rendering the same session overwrites its file and refreshes its index entry. Pass `--library <dir>` for another folder, or `-o <file>` / `--no-library` for a single standalone page with no library around it. On the index page, each card's hide button takes a session out of the list and the switcher in that browser; the page stays on disk, and "Hidden (N)" brings it back. A session that is still running shows as Live and can't be hidden. Only when the user asks you to delete sessions for real, run `npx -y [email protected] delete <session-id>...` (or `--all`). It deletes their pages and rewrites the index; an id prefix of 4 or more characters is enough. It refuses a running session unless `--force` is passed, and `--all` keeps running sessions. 5. Report both paths — the story page and `.session-stories/index.html` — and the header numbers (turns, files, lines added/removed, outcome) to the user. If the story has token usage, report output tokens, the cost when recorded, and which turn used the most output tokens (the Report tab's "Where it went" ranks them). 6. **Optional: markdown.** If the user asks for a PR description or a handoff for a fresh session, run ```bash npx -y [email protected] export <scratch>/story.json [--template handoff] ``` and give them the output (or pipe it to `pbcopy`). Every line comes from story.json; paste it as is and add no claims of your own. Files outside the project are left out unless `--all-files` is passed. ## Limits - Claude Code sessions only (v1). Codex/Cursor/OpenCode are out of scope. - `Edit`, `Write`, and `NotebookEdit` calls are read from the transcript. Changes made through `Bash` (`sed -i`, a heredoc script, a formatter) carry no diff there, so they are recovered from git instead: the tree is compared from the commit the session started on through to the working tree, and each change is credited to the turn whose commands account for it. Those edits are labelled on the page, and come with git's limits — a file edited again after the session shows both changes, and a commit made during the session by someone else looks like the session's own. Pass `--no-git` to `extract` to skip the git pass entirely (this also skips `report.git`; `report.dependencies` is still extracted). - `report.plan`, `report.decisions`, `report.outcome`, `report.outcome_note`, and `errors[].resolution` are Claude's judgement calls, not something the extractor can verify — write them honestly from what the brief shows, including when the outcome isn't a clean success. - A story page copied out of `.session-stories/` loses only the "All sessions" link and the switcher (they stay hidden when the sibling `sessions.js` is missing); everything else still works from `file://`. - Requires Node.js 18.18+ and no other dependencies.session-story/.claude-plugin/icon.png11 KBd9cac66f1c25upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
session-story/.claude-plugin/plugin.json582 Bc0d294a36580upstream ↗
{ "name": "session-story", "version": "0.6.0", "description": "Generate a self-contained HTML session story that links each prompt to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative.", "author": { "name": "Nenad Alajbegovic", "url": "https://github.com/nalaj" }, "homepage": "https://nalaj.github.io/session-story/", "repository": "https://github.com/nalaj/session-story", "license": "MIT", "keywords": ["claude-code", "agent-skill", "session-replay", "code-review", "diff"], "skills": ["./"] }session-story/LICENSE1.0 KB7ed49f544da3upstream ↗
MIT License Copyright (c) 2026 Nenad Alajbegovic Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.session-story/schemas/story.schema.json44 KBc1849ce57448upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/nalaj-session-story-session-story.md