The files are the edit

Open a BetterEdits video in Finder and you find a folder with three files and a media folder. project.json holds the canvas, the brief and the media by name. timeline.json holds the tracks, one clip per line. styles.json holds the looks. That is the whole video.

The app is a viewer and a hand tool for those files. This is the decision the rest of the product follows from.

Written for reading

The files are laid out for a person, or an agent, to read. Keys in reading order. Defaults left out. No ids anywhere: a clip is its position, a track its name, a file its name. A clip on a magnetic track carries no times, because its time is where it sits in the list.

A timeline of a talking head looks like this:

{
  "tracks": [
    { "name": "Subtitles", "kind": "subtitles", "style": "Bold Outline", "position": "bottom",
      "bars": [ { "s": 0.0, "e": 1.8, "text": "Three rounds a week." } ] },
    { "name": "Video 1", "kind": "video", "clips": [
      { "media": "take-3.mov", "in": 2.4, "out": 9.1 },
      { "media": "take-3.mov", "in": 10.2, "out": 16.8, "note": "the hook" }
    ] },
    { "name": "Music", "kind": "audio", "clips": [ { "media": "lofi.m4a", "at": 0, "in": 0, "out": 16.3, "volume": 0.4 } ] }
  ]
}

You can read the edit without opening the app. So can Claude.

The app writes back, and reads back

Every change you make in the app is on disk a third of a second later. There is no save, no dirty state, no recovery prompt.

Every change made to the files by anything else is picked up within a second and applied as one undo step called Edit on Disk. Claude writes the whole timeline in one go, the app takes it, and ⌘Z takes it back.

The reader is strict on purpose. An unknown key, a file that is not in the project, an out point past the end of the footage, two clips overlapping on a free track: each is refused with the file and the place. The app keeps its own copy and stops writing over the file until it is fixed, and a linter checks a project without the app at all. Strictness is what makes it safe to let an agent write.

What it buys the agent

An agent is good at text and bad at pixels. Give it a timeline as text and it can read the whole edit at once, reason about it, and rewrite it. Give it a strict reader and it gets told exactly where it went wrong instead of silently producing something broken. Give it a command line for the single precise steps, a split here, a caption fix there, and it has both the pen and the scalpel.

The workspace guide the app writes tells Claude all of this, with an example, so the format never has to be guessed.

What it buys you

Your video is a folder. Put the workspace in git and every cut is a readable diff. Back it up like any folder. Open a timeline in a text editor and change a number. Hand a project to a friend and they can open it in the app, or read it without the app.

Footage is never duplicated. Files in your media folders are used where they are; a one-off file is copied once into the video's own folder, so the folder is complete on its own.

Nothing is locked inside the app. If BetterEdits vanished tomorrow, your edits would still be readable text next to your footage.

The trade

The cost of this design is a smaller editor. No effects graph, no keyframe curves, no plugin store, because each of those would make the files unreadable and the reader unstrict. For the long-form piece that needs them, use Final Cut. For the short video you make every week, readable files and an agent that can write them are worth more.