cardboard31.9 KB
View saved version →
---
name: cardboard
description: "Edit Cardboard video projects (.cardboard bundles) with the `cb` CLI and timeline.tsx, or with Cardboard's tools: cut, arrange, caption, add titles and motion graphics, color grade or match a reference look, generate footage, narration, music or sound effects, import video links, and check the result with look. Use when a task mentions Cardboard or `cb`, a .cardboard folder or timeline.tsx is in view, or Cardboard's tools are connected."
---
# Cardboard
A Cardboard project is a folder, `<Name>.cardboard/`, whose **`timeline.tsx`** is a literal TSX mirror of the timeline
that Cardboard regenerates on every save. Edit it and save, and the project changes; an open app follows within ~200 ms
as one undo step.
`cb` (alias of `cardboard`) is on PATH once the app's **File › Install Agent Tools…** has run, or via `pnpm cli` in the
repo. Commands that work on a project take its **name, id or bundle path**, and every command accepts `--json`.
`cb docs <topic>` prints command documentation and techniques; the same files sit in `commands/` and `techniques/` next
to this skill. Follow the matching technique for titles and motion graphics (`cb docs motion-graphics`), synced captions
(`cb docs synced-captions`), behind-subject compositing (`cb docs behind-subject-compositing`), color grading and
matching a reference look (`cb docs color-grading`), and any 3D scene, object, character or 3D camera move, including
whether to build it in three.js or generate it (`cb docs 3d-scenes`).
## In Claude or ChatGPT, in the cloud
With Cardboard's tools and neither `cb` nor the Cardboard app on this machine, you are editing the human's Cardboard
project from inside their Claude or ChatGPT chat, on a phone or a computer. Cardboard runs in the cloud here: there is
no app, no file and no timeline on their screen, and the tools are the only way in. What this guide says about `cb`,
`timeline.tsx`, saving and the app does not apply.
**What the human sees** is this chat and Cardboard's cards in it.
- The upload card (`upload_media`) is how footage and photos on their device get in. They pick video, audio or photos
(JPEG, PNG, HEIC, WebP or GIF), and the card shows each file's progress. Once they are in, its Start editing sends a
message saying what arrived and to start editing; in Claude it lands in their message box for them to send. When
they've said what to make, pass `goal` as the short phrase the card shows after "Ready to make", addressed to them
("your 1-minute travel montage"). The card lists nothing until they choose files from their device, so ask them to
choose the clip there, never to "select <file> in the card".
- In ChatGPT, video, audio and photos attached to the chat go into the project through `add_media`, the same as an
upload from the card, so there's nothing to upload again. In Claude, attachments don't reach Cardboard: when they
attach one, say so once and open the card.
- The player card is how they watch: it plays the project's latest edit once it has rendered, and an export plays in the
same card and offers the download, so there is no file or link to share. A reply that changes the timeline ends with
one player on its last edit, however many edits it took. In Claude, edits show nothing by themselves: call
`show_preview` once, after the reply's last edit has landed (an edit handed back as a job lands when `job_status`
says it is done), then write the reply. In ChatGPT the reply's card follows each edit, so it needs no call. Earlier
replies' players fold above it.
- Each player is labelled with its edit ("Edit 3"). When they want an earlier edit back, restore that one:
`timeline_history` marks which revision each edit is, and `undo_timeline` with that `rev` brings it back as a new
edit, keeping the later ones. Say it's back, and that the edit they moved on from can come back too.
- The projects card (`show_projects`) is how they see their projects: the most recently editePreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
