keyframes

HTML slide decks that LLMs write and you arrange by hand.

• Slides are plain HTML files on a fixed 1920×1080 canvas. Claude Code, Codex & co. write them from your references; a generated AGENTS.md teaches them the format.
• Live editor in Chrome: press E to drag, resize, snap and nudge blocks. Changes are written straight back into the slide source (only the touched attributes change), so your layout and the LLM's edits never fight.
• Rich embeds as web components: three.js scenes, MuJoCo WASM physics, editable/runnable code (JS + Python via Pyodide), Excalidraw figures, KaTeX math, video.
• Present anywhere: presenter view with notes and timer, offline-safe dependency cache, PDF export, static site export.

Quick start

uv init my-talk && cd my-talk
uv add keyframes            # or: uv add 'keyframes[export]' for pdf/shot/check --render
uv run keyframes init .
uv run keyframes dev        # opens Chrome; edit slides/*.html or ask your LLM to

Then ask your agent something like "Using the papers in references/, draft a 12-slide talk on X. Put the MuJoCo demo from assets/ on slide 5." and rearrange the result with E.

For exports install the browser once: uv run playwright install chromium (or have Chrome).

In the browser

Editor: drag to move (Shift locks axis, Alt disables snapping), handles resize (Shift keeps aspect), arrows nudge (Shift ×10), [/] z-order, double-click to interact with a live embed, C copies a block reference like slides/04-results.html#sim for your next prompt, ⌘Z / ⌘⇧Z undo/redo, ? for help.

Edit mode also opens a resizable side panel (toggle with `):

• Source: the current slide's HTML. Selecting a block jumps to its tag; edits save and hot-reload as you type; drags and LLM edits flow back in.
• Claude / Codex / Shell: real terminals running in the deck folder (whichever CLIs are installed). Sessions survive page reloads. + ref (or R) types the selected blocks' reference into the prompt, e.g. @slides/04-problem.html (block "figure").

The dev server only accepts editor/terminal requests from its own page, but it does give that page a shell: keep it bound to 127.0.0.1 (the default).

Commands

keyframes init [path]        new deck from the scaffold
keyframes dev                live server + editor
keyframes present            serve without the editor
keyframes check [--render]   lint; --render adds browser errors and text overflow
keyframes shot [N ...]       PNG screenshots → .keyframes/shots/
keyframes pdf                PDF export (one page per slide, all builds shown)
keyframes build              static site → dist/
keyframes guide              full authoring reference (for LLMs)
keyframes themes             list built-in themes
keyframes eject-theme        copy the theme into the deck to customize it

Deck layout

my-talk/
  deck.toml        title, theme, canvas size, extra <head> tags, extra ES module imports
  AGENTS.md        authoring rules for LLMs (CLAUDE.md imports it)
  slides/          01-title.html, 02-motivation.html, ...  (ordered by filename)
  assets/          images, video, MJCF models, three.js scene modules, .excalidraw files
  references/      papers/notes for the LLM to draw from (never exported)
  .keyframes/    dependency cache + screenshots (gitignored)

Themes

• default: a clone of Google Slides' "simple-light" template (Google Sans + Roboto Light, orbit artwork on title/section slides, split layouts with a grey media panel).
• minimal: plain Inter/JetBrains Mono theme.

A theme is a folder with theme.css (CSS variables + text/container classes), STYLE_GUIDE.md (rules the LLM follows) and layouts/*.html (starting-point slides). Use theme = "./theme" in deck.toml for a deck-local theme.

Development

uv sync --all-extras
uv run pytest
uv run ruff check src tests && uv run ruff format src tests
cd examples/showcase && uv run keyframes dev   # every component in one deck