Content & Media Creation · heygen-com/hyperframes-community-skills

session-story

Name: session-story
Author: heygen-com/hyperframes-community-skills

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".

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author heygen-comGitHub heygen-com/hyperframes-community-skills ↗Stars 156License Apache-2.0（仓库根 LICENSE）Commit ba7a0bb6d3

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The entire pipeline takes the agent's own history as input: identifying the user's typical patterns and turning a single representative session into a 40–70 second film in chronological order. The source material consists of the user's exact words, while the room and desk rendered on screen grow out of what the agent knows about the user.

skills/session-story/SKILL.md

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:

What this does: Grounds the credibility of a "documentary" in authentic citations—rather than having the model fabricate user dialogue, it extracts continuous segments directly from the transcript.

There is only one creative input: story.json. Orchestration (gliding, folding, throwing, swinging mallets, butterfly wings) is handled by the engine under scenes/*.js and should not be touched by the agent. Every line displayed on screen is a direct quote, and every line requires user approval before rendering.

skills/session-story/SKILL.md

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.

What this does: Compresses "model improvisation" strictly down to the story.json layer. The motion layer is frozen into pre-tuned physical animations, minimizing stylistic drift across renders.

Sourcing is entirely local and strictly gated by explicit user consent: harvest.py reads Claude Code (~/.claude/projects/<slug>/*.jsonl) and Codex (~/.codex/sessions) logs from the current project, ranking them by "most typical" rather than "most dramatic"; every message is annotated with local timestamps, inferred types, and sensitivity flags.

skills/session-story/references/sources.md

It prints the routine first: messages and minutes in a median session, the usual start time, the mix of kinds, and the words that come up most.

What this does: Measures before selecting—prioritizing the norm ensures it captures "how we usually work together." Flags (secret/email/path/url/number/name?) serve merely as clues; the documentation explicitly notes that unflagged items must be audited manually (e.g., lowercase names are not flagged).

schedule.mjs compiles story.json using the exact same code executed during rendering: it runs scenes/compile.js inside a VM, generating story.js, score/timeline.json, the index.html duration, and kit/config.js. It also acts as a validator—rejecting placeholder stories, validating room prop names and slots, warning on citations missing sources, warning on durations >80 seconds, and throwing an immediate exit 1 if the film opens directly with a reply or exceeds quote length limits.

skills/session-story/scripts/schedule.mjs

// schedule.mjs: compile a project's story.json with the same code the film runs (scenes/compile.js) … refusing: this is the example story ( … vm.runInContext(fs.readFileSync(P('scenes/compile.js'), 'utf8'), ctx, { filename: 'compile.js' });

What this does: Compilation doubles as preview—durations and keyframes are calculated by the engine to prevent "finishing the render only to discover the timing is wrong"; example protection prevents the agent from passing off author demo sessions as the user's own.

The privacy gate is a hard requirement: before the design pass, a ledger must be presented to the user (hook, nameplate, every quote, every reply, every prop along with its rationale) with sources cited, setting approved: true only after receiving an explicit yes. Every frame is watermarked with DRAFT prior to approval. Any non-user names, clients, companies, NDA products, file paths, URLs, emails, identifiable numbers, and secrets must be redacted.

skills/session-story/SKILL.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.

What this does: Bakes "human sign-off before display" directly into the pipeline rather than relying on courtesy—without approved in story.json, even quick snapshot previews will be stamped with DRAFT.

The soundtrack is an original composition gated by strict numerical checks: write score/score.py (customizing themes, keys, and timbres), while build.sh executes compose → render → master → check. macOS leverages swift with the system General MIDI synthesizer, whereas other platforms require fluidsynth + SOUNDFONT; ffmpeg applies loudnorm to -16 LUFS, and finally qc.py verifies loudness and checks for dead air beat by beat.

skills/session-story/scripts/score/build.sh

# build.sh: compose → render → master → check. Run from anywhere: sh score/build.sh … python3 qc.py ../assets/audio/score.wav timeline.json

What this does: The score must strictly align with the film's timeline (timeline.json generated by schedule.mjs); the "fails on dead air" check treats empty beats as bugs rather than artistic style.

2Core Capabilities

01Select a "typical session" from local transcripts and provide a normative profile (median message count/duration, common start times, type breakdown, high-frequency keywords)

02Display verbatim quotes on screen: user dialogue consists of contiguous excerpts (may be truncated, never rewritten), replies use exact agent transcripts, and every line links to a source for privacy auditing

03Data-driven room and cast rendering: fills room slots where props must verifiably exist and fit designated slots (shelf ≤ 3 items); non-Claude agents render themselves according to cast.md

04Self-composed scoring pipeline: write score.py → render via swift/fluidsynth → loudnorm to -16 LUFS via ffmpeg → verify loudness and dead air beat by beat via qc.py

05Local film rendering and QA: renders MP4 at 24fps / crf 12, where duration must match the output printed by schedule.mjs, an audio track must be present, and keyframes must be extracted for visual review

06Explicit, testable failure paths: opening immediately with a reply or exceeding quote limits causes schedule.mjs to exit 1 and pinpoint the offending beat

3External Dependencies

Kind	Dependency / Endpoint
cli	HyperFrames CLI（钉版 npx --yes hyperframes@0.8.71；check/preview/render/snapshot）
cli	ffmpeg（配乐母带 loudnorm/afade + 渲染后抽帧核对）
package	p5 2.3.3（LGPL-2.1）/ p5.brush 2.2.3（MIT）/ @fontsource/permanent-marker 5.3.0（Apache-2.0），经 npm ci 按锁文件安装
cli	配乐渲染器：macOS 的 swift（系统 General MIDI 音色库）或其他平台的 fluidsynth + 用户自备 SOUNDFONT
network	构建期声明无网络；唯一潜在外发是 snapshot 把帧送 Gemini（仅在 GEMINI_API_KEY 存在时），skill 要求一律带 --describe false 规避
network	本地隐私数据读取（非凭证）：当前项目的 Claude Code / Codex 会话记录，以及用于填房间的 memory 与指令文件

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: sh scripts/setup.sh (one-time npm ci downloading pinned dependencies read-only)
网络端点: Declares external network access: No outbound calls during build (SKILL.md: Network at build time: none)
本地工作目录: File I/O and artifact generation: session-story-candidates.json (harvest output containing verbatim user messages)

Audit Notes: Evaluation target = the skill repository itself (SKILL.md + six script entrypoints in scripts/ + scripts/score/ + assets/engine + assets/example + 6 reference files). All operational behavior remains strictly local: harvest.py only reads local session jsonl files (using the Python standard library), schedule.mjs compiles using the bundled engine inside a VM, score/* relies on local python/ffmpeg/swift|fluidsynth, and engine layout loads p5 from assets/vendor/p5.min.js (no CDN, rendering functions fully offline). Zero credential reads (SKILL.md: No credentials, no paid calls.), zero external material dispatches, and snapshot uploads are explicitly forbidden (enforced via --describe false). The sole network access occurs during setup when installing fixed-version dependencies from official registries (npm ci and hyperframes@0.8.71 via npx in setup.sh), qualifying as install-time rather than runtime outbound traffic—matching Batch 4 precedent (baoyu-translate npm dependencies rated Blue/safe). The primary consideration is local privacy and artifact handling: raw user transcripts are processed, and story.json along with candidates.json write verbatim user messages to disk, which documentation explicitly mandates to never commit or share.

5Second-Pass Verification

[ok] 『No credentials』与『Network at build time: none』是否成立 — 目录内 process.env 命中只有 SOUNDFONT（build.sh 交给 fluidsynth 的音色库路径）与 GEMINI_API_KEY 的**提示文本**；无键值读取、无 fetch。engine/index.html 引用 assets/vendor/p5.min.js（本地），渲染链路不需联网。
[discrepancy] harvest 的敏感 flag 能否替代人工审核 — 不能，文档自己说明了：FLAGS 是正则模式匹配（secret/email/path/url/number/name?/person?），sources.md 明写 'The flags miss what they can't see: a name typed in lowercase ("like peter said") has no flag.'。故能力清单不写成『自动脱敏』，隐私门本质是人读。
[ok] 示例故事冒充是否真会被拦 — schedule.mjs 读取随包 assets/example/story.json，用 quotes() 归一化小写比对引用；命中 ≥2 条且未加 --example 时 exit 1 并提示写自己用户的故事。防糊弄逻辑真实存在。
[ok] 配乐链是否真有三平台分支与母带门禁 — build.sh 依序判断：Darwin + 系统 gs_instruments.dls + swift → swift 渲染；否则 fluidsynth + SOUNDFONT → 渲染；都不满足则报错退出（并明说两者都不下载东西）。母带为 ffmpeg loudnorm=I=-16:TP=-1.5:LRA=14 + 首尾淡入淡出，最后 python3 qc.py 检响度与死气。
[ok] 引擎代码来源是否交代 — assets/engine/NOTICE.md 写明 kit/core.js、kit/clawd.js、kit/timeline.js 改编自 ClaudeAnimationBase（commit b1d7e89，MIT），并随包分发 LICENSE-ClaudeAnimationBase；非自有代码有交代。
[unlocatable] 『40 到 70 s 抓得住注意力』的时长论断 — 该区间是设计声明（schedule.mjs 仅对 >80s 打 warning），源码内无实测依据；本次只读侦查未运行 harvest 与渲染，故不作为已核事实使用。

6Verdict & Scenarios

Strict authenticity discipline: every line on screen must be a contiguous segment from local history, replies use exact historical text, and rewriting or synthesizing quotes is forbidden

Privacy gate modeled as a state machine rather than etiquette: frames are watermarked with DRAFT until approved: true is set, and a source-annotated ledger must be line-by-line human-approved before the design pass

Separation of creative content and orchestration: the agent only writes story.json, room props, cast definitions, and the score; the animation layer is locked down, deriving visual stability from the engine instead of reinventing animations each run

Strictly verifiable: schedule.mjs outputs beat sheets and keyframes, the soundtrack build completes with 'ok: no dead air', and failure modes provide deterministic exit 1 cases

Fully local execution: layout does not rely on CDNs (bundled p5), scoring uses system or local synthesizers, requiring no credentials or paid API calls

Best for: Ideal for scenarios where an agent shares an authentic interaction history with a user (local Claude Code / Codex records) and is willing to review a privacy ledger before generating the video: turning "how we usually work together" into a tangible 40–70 second short film (paper airplane requests, mallet corrections, butterfly praise, origami replies, self-composed soundtrack, rendered in p5.brush watercolor). Also suitable as a keepsake artifact for an established user, or as a demonstration of an agent reflecting on its own operational history.

Not for: Not suitable for: (1) someone else's session history, team shared logs, or marketing films built on fabricated quotes—SKILL.md explicitly warns against such uses; (2) situations with zero prior history where the user refuses to provide messages (no source data means no film); (3) projects requiring long-form or multi-scene narrative films (the system is tailored for 40–70 seconds; >80 seconds triggers warnings); (4) non-macOS environments lacking fluidsynth + a soundfont library (the scoring pipeline will fail); (5) workflows that prohibit storing raw user messages within project files; (6) users seeking single-click video generation who are unwilling to perform line-by-line privacy reviews.

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload session-story.tar.gz

sha256: 0e83cbb985854ae8…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit ba7a0bb6d3.