Skip to main content
skill CX Codex

session-story — Claude Code skill: session logs into animated film

session-story — a skill for Claude Code that turns user interaction history into an animated film. The agent analyzes session logs to visualize the workflow in real time.

Apache-2.0 847 installs ★ 286 updated 2026-11-04

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add heygen-com/hyperframes-community-skills --skill session-story -a claude-code
Open on GitHub

What session-story does

This skill reads dialogue history and compiles it into a short film lasting 40 to 70 seconds. The agent simulates its workflow: requests arrive as paper planes, corrections appear as a 3D mallet, and praise manifests as a butterfly with a ribbon. The script, room decor, and orchestral score are generated based on the user's specific routine and project context.

Operation requires Node 22+, Python 3.9+, and ffmpeg in the system PATH. Rendering is handled by HyperFrames, while audio on macOS uses swift for General MIDI access, with fluidsynth used on other systems. The skill processes local session logs only and does not upload user data to the cloud.

What it helps with

  • visualize agent interaction history
  • create an animated session report
  • convert text logs into a short film

Example prompts for the agent

  • Animate a video of our session
  • Make a film about me and my agent
  • Show what working with me is like

How to install session-story

1Skills CLI (Vercel)

npx skills add heygen-com/hyperframes-community-skills --skill session-story -a claude-code

2Manually: put the files in place

~/.claude/skills/session-story/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/session-story/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about session-story

How to install session-story in Claude Code?

Run npx skills add heygen-com/hyperframes-community-skills --skill session-story -a claude-code in your terminal.

What does session-story do?

It analyzes conversation history to identify typical sessions and produces a 3D animation where the agent performs tasks, representing messages and actions as physical objects.

What is required for session-story?

You need Node 22+, Python 3.9+, ffmpeg in your PATH, and the HyperFrames CLI version 0.8.71.

Source text

SKILL.md · Apache-2.0
---
name: session-story
description: >
  An agent makes an animated film of an average session with its own user, beginning to end, told with that user's
  real messages: whatever their routine is (code, writing, data, design, video). The agent sits at a desk in a room
  decorated from what it knows about the user, and the monitor shows their kind of work. Requests glide in as paper
  planes and unfold. Corrections are a 3D cartoon mallet that bonks, then turns to show the words on its face. Praise is a butterfly
  towing the words on a ribbon. The agent types each reply onto a sheet, folds it and throws it back. The film opens
  with the agent asleep until the monitor boots: "Initiating session with <name>". The agent composes its own
  orchestral score, cued to every action. p5.brush watercolour, rendered in HyperFrames. Trigger on: "a video of our
  session", "animate a session with me", "session story", "show what working with me is like", "make a film about
  me and my agent".
---

# Session story

The agent reads its own history with its user, finds their routine, and turns one typical session into a 40 to 70 s
film, in the order it happened:
- **Story:** the user's verbatim words arriving as objects, and the agent's own replies going back. The window and
  the wall clock follow the session's real time.
- **Room:** decorated from what the agent knows about its user.
- **Score:** composed by the agent against the film's own timeline.

Write `story.json` and the engine does the choreography. Nothing on screen is invented: every line is a quote, and
the user approves every line before a frame is rendered.

## When to use / when not

- **Use** when a user asks their agent for a film of their work together, and the agent has real history with that
  user: local transcripts, or messages the user pastes in.
- **Do not use** for someone else's history, a team's shared logs, marketing with made-up quotes, or anything the
  user won't review. With no history at all, ask the user for a session's messages. Never invent quotes.

## Requirements and side effects (complete list)

- **Tools:** Node 22+, Python 3.9+ (standard library only), `ffmpeg` on PATH, and the HyperFrames CLI pinned to
  `npx --yes [email protected]` (downloaded from the npm registry on first use).
- **Setup (once, manually):** `sh scripts/setup.sh` runs `npm ci` from the committed lockfile: p5 2.3.3 (LGPL-2.1),
  p5.brush 2.2.3 (MIT), @fontsource/permanent-marker 5.3.0 (Apache-2.0). Read-only downloads from npm.
- **Score renderer:** on macOS, `swift` (Xcode Command Line Tools) plays the score through Apple's built-in General
  MIDI bank. Elsewhere, `fluidsynth` with a General MIDI soundfont you set as `SOUNDFONT`. Neither downloads anything.
- **Reads (local only, after the user says yes):** the agent's own transcripts, `~/.claude/projects/<project>/*.jsonl`
  (Claude Code) and `~/.codex/sessions` (Codex), for the current project unless the user allows `--all-projects`.
  Also the agent's memory and instruction files for the room. Nothing is uploaded.
- **Writes:** `session-story-candidates.json` (harvest) and everything inside the project folder you create. Both hold
  the user's words: never commit or share them.
- **Network at build time:** none. Pass `--describe false` to every `snapshot`, as shown below: with
  `GEMINI_API_KEY` set, `snapshot` otherwise sends frames (the user's words) to Gemini. Render locally: the page paints
  with WebGL.
- **No credentials, no paid calls.**

## Workflow

1. **Setup:** `sh scripts/setup.sh` (once).
2. **Ask first.** Tell the user you'll read your local history with them to find the session, and wait for a yes.
3. **Harvest:** `python3 scripts/harvest.py --project <their project folder> --out <scratch>/candidates.json` prints
   the routine and lists sessions, most typical first. `--session <id>` (with the same `--project`) prints one in
   order, with local times and your replies. Per [references/sources.md](references/sources.md).
4. **Scaffold:** `node scripts/new-project.mjs <dir>`. Everything you write from here lives in `<dir>`.
5. **Story:** take a typical session and write `<dir>/story.json` beat by beat, in the order it happened, with each
   beat's real time, per [references/story.md](references/story.md). The user's lines are verbatim spans; your replies
   are your own words from that session. Set `screen` to what their work looks like, and pick the ending their
   sessions have. `node scripts/schedule.mjs <dir>` checks it: run it after every edit.
6. **Room:** fill the slots from what you know about the user, per [references/room.md](references/room.md). Draw a
   custom prop in `<dir>/scenes/props-custom.js` when the library has nothing true to them. If you are not Claude,
   draw yourself: [references/cast.md](references/cast.md).
7. **Privacy gate:** show the user one table of every on-screen line (hook, nameplate, each quote, each reply, each
   prop and why), each with its source. Take their edits, get an explicit yes, then set `"approved": true`. Until
   then every frame carries a DRAFT stamp.
8. **Design pass:** run the `snapshot` command `schedule.mjs` prints. Look at every frame: quotes legible, props where
   they belong, nothing covering a message. Show the user the contact sheet.
9. **Score:** write `<dir>/score/score.py` with your own theme, key and palette, per
   [references/score.md](references/score.md). Then `sh <dir>/score/build.sh`. It fails on dead air.
10. **Render:** from `<dir>`: `npx --yes [email protected] check`, then
    `npx --yes [email protected] render --fps 24 --crf 12 -o renders/session-story.mp4`.
11. **Check the render:** its length must match `schedule.mjs`. Pull a frame at each key moment
    (`ffmpeg -ss <t> -i renders/session-story.mp4 -frames:v 1 renders/check-<t>.png`) and look at them. Then hand
    it to the user to watch with sound.

The example (`node scripts/new-project.mjs <dir> --example`, then `schedule.mjs <dir> --example`) is the reference
film: a real session between Claude and the skill's author, who makes videos. It shows the format, not the shape of
your film. `schedule.mjs` refuses it without `--example`, so it can't stand in for your user's story.

## Verify success

- `schedule.mjs` exits 0 and prints no warnings. `hyperframes check` passes. p5.brush logs WebGL `uniform`
  warnings, which are harmless.
- The design-pass frames show every quote legible, and match the beat table.
- `score/build.sh` ends with `ok: no dead air`, and the score's length matches the film's.
- The render is the length `schedule.mjs` printed, has an audio track, and its frames at the key moments match the
  design pass.
- Failure path to test: a story that opens on a reply, or has a quote over the limit, makes `schedule.mjs` exit 1
  and name the beat.

## What the engine owns

The motion is physical and already tuned: glide paths, the fold, the throw, the swing, the bonk and the wingbeats.
Change the story, the room, the cast and the score. Leave the choreography in `scenes/director.js` and
`scenes/compile.js` alone unless you are fixing a bug. The motion rules are in
[references/motion.md](references/motion.md).

© heygen-com · Apache-2.0 · heygen-com/hyperframes-community-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set8

Project sponsors

Companies that keep this analytics open