openklip: Instructions file for Codex

AGENTS.md

Single source of truth for AI agents working in this repo: OpenKlip editing workflow, guardrails, copy rules, and code standards.

---

OpenKlip agent skill

OpenKlip is a local-first, agent-native video toolchain: external agents run the edit loop via CLI; the browser reviews the same project.json.

The file model (read this first)

Each project lives as plain files under projects/<slug>/ in a layered layout. The parent directory is resolved by projectsRoot():

1. OPENKLIP_PROJECTS_ROOT if set
2. else .openklip/projects-root in the app cwd (GUI folder picker)
3. else ~/Movies/OpenKlip

projects/<slug>/
  project.json            the EDL - the edit itself (the only file you edit)
  brief.md                optional project brief: audience, goal, tone,
                          must-use assets, avoid list, target length, formats
  assets/                 user originals (flat): drop b-roll, music, stills here
  graphics/               optional project-local graphic templates (override bundled ids)
  working/                derived media + scratch: proxy.mp4, transcript.json,
                          audio16k.f32, frames/, asset proxies, chats.json,
                          actions.jsonl, tasks.json…
  output/out.mp4          the rendered export

Edit templates (repo root, not per project):

templates/<id>/skill.md   agent playbook (cuts, overlays, export loop)

Optional template field on project.json points at a template id (e.g. talking-head).

project.json IS the edit. It holds every transcribed word with a deleted flag, b-roll overlays, still (Ken Burns) overlays, push-in zooms, title cards, graphics (HTML/CSS template overlays), music placements, captions settings, look flags, optional sceneLog (visual spans + speaker focus), optional highlights (LLM clip candidates), and export (aspect + reframe crop). Everything under working/ and output/ is regenerated from it. The GUI editor and these CLI commands both read and write this same file; they are equivalent (parity). Edit it through the CLI; the browser editor will show the same result, and vice-versa.