Claude Skill

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, "w

LLM Mart · 0 points · 8 views 45 listing impressions 0 install-command copies
Download nalaj-session-story-session-story-9ae8339.zip · 125 KB

Install

skills CLI npx skills add https://github.com/nalaj/session-story/tree/main/session-story
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nalaj-session-story@llmmart
Git git clone https://github.com/nalaj/session-story.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nalaj/session-story collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

<skill-dir> below is the directory that contains this SKILL.md (where the skill was installed). Run every command from the user's project directory, not from <skill-dir>, 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:

    node <skill-dir>/bin/story.mjs 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.

    node <skill-dir>/bin/story.mjs validate <scratch>/story.json --strict
    

    If this reports missing summaries or report fields, go back to step 2.

  4. Render.

    node <skill-dir>/bin/story.mjs 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 node <skill-dir>/bin/story.mjs 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

    node <skill-dir>/bin/story.mjs 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.
Files (session-story)
  • .claude-plugin
    • icon.png 10.8 KB · in bundle
    • marketplace.json 1013 B
      Loading…
    • plugin.json 582 B
      Loading…
  • bin
    • story.mjs 19.1 KB · in bundle
  • schemas
    • story.schema.json 43.9 KB
      Loading…
  • src
    • ir
      • commands.mjs 3.6 KB · in bundle
      • cross-index.mjs 2 KB · in bundle
      • dependencies.mjs 5.6 KB · in bundle
      • disk-base.mjs 2.4 KB · in bundle
      • file-state.mjs 3.3 KB · in bundle
      • git-edits.mjs 16 KB · in bundle
      • git-state.mjs 3.4 KB · in bundle
      • metrics.mjs 13.6 KB · in bundle
      • selectors.mjs 1.4 KB · in bundle
      • trace.mjs 8.9 KB · in bundle
      • validate.mjs 6 KB · in bundle
    • render
      • diff.mjs 7.8 KB · in bundle
      • full-view.mjs 1.9 KB · in bundle
      • hunk-html.mjs 4.2 KB · in bundle
      • icons.mjs 3.6 KB · in bundle
      • inert.mjs 984 B · in bundle
      • lenses.mjs 29.6 KB · in bundle
      • library.mjs 35.1 KB · in bundle
      • markdown.mjs 8.5 KB · in bundle
      • metrics-blocks.mjs 12.3 KB · in bundle
      • report.mjs 10.4 KB · in bundle
      • story-data.mjs 4.8 KB · in bundle
      • template.mjs 56.2 KB · in bundle
      • theme.mjs 5.5 KB · in bundle
    • transcript
      • bash-edits.mjs 5.8 KB · in bundle
      • claude-code.mjs 30.4 KB · in bundle
      • live.mjs 1.5 KB · in bundle
      • locate.mjs 7.8 KB · in bundle
      • parse.mjs 903 B · in bundle
      • paths.mjs 1.2 KB · in bundle
  • LICENSE 1 KB · in bundle
  • package.json 390 B
    Loading…
  • SKILL.md 10.1 KB
    ---
    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.5.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.
    
    `<skill-dir>` below is the directory that contains this SKILL.md (where the
    skill was installed). Run every command from the user's project directory,
    not from `<skill-dir>`, 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
       node <skill-dir>/bin/story.mjs 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
       node <skill-dir>/bin/story.mjs validate <scratch>/story.json --strict
       ```
       If this reports missing summaries or report fields, go back to step 2.
    
    4. **Render.**
       ```bash
       node <skill-dir>/bin/story.mjs 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 `node <skill-dir>/bin/story.mjs 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
       node <skill-dir>/bin/story.mjs 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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.