# How an agent edits

> The round trip an agent makes through the app, what it can and cannot do, one undo step per change, the starter prompts, and prompts that work.

An agent never edits a file. It asks the running app for the open video as one JSON document, changes it, and hands it back; the app checks every line and applies it as one undo step, live, while you watch. This page explains that round trip, what the agent can do with it, and how to ask. It is part of [Pro](https://betteredits.app/docs/pro); the setup is on [Connect an agent](https://betteredits.app/docs/connect-agent).

## The round trip

1. `status` says which workspace is open, which video is the agent's and whether it is shown in a window, and whether this Mac has Pro. `projects` lists every video and how it stands; `project-open` makes one the agent's, in the background, without touching your windows; `app-show` puts a window on it. Two agents can work on two videos at once, and either can act on another video by naming it.
2. `project-get` returns the video as one document: `project` (the canvas, the brief, notes and the media by name), `timeline` (the tracks with their clips and bars), `styles` (the looks), plus a `revision`, `computed` (every clip with its start and end worked out) and `reference` (the rules of the document).
3. The agent reads what the footage holds when it has been analysed (`transcript`, `analysis`, `media`), or looks with `contact-sheet` and `levels`. See [Analysing footage](https://betteredits.app/docs/analysis).
4. `project-commit` takes the edited document back with the revision it came from. The app reads it strictly and lints it: a stale revision, a misspelt key, a media name that is not in the document, an `out` past a file's end, two clips overlapping on a free track, or a change to a locked track is refused with every problem and its place, and nothing changes. `lint` is the same check without applying.
5. The commit lands as one undo step called Agent Edit, the app writes the files, and the answer carries the new revision. The agent looks at the result with `contact-sheet --clips` and `frame` (the true composite, graphics included), listens with `mix` (`--audio` hands it the mixed sound as a WAV to measure), compares a copy with its reference with `contact-sheet --against`, and only renders `export --preview` for motion; `seek` and `select` put you on the moment it is talking about.

A commit that arrives after you edited by hand is refused, because the revision moved on; the agent fetches the document again and redoes its edit on yours. Nothing the agent does can reach a state the window cannot, and ⌘Z takes any step back.

The document's shape, every key and every rule, is in the guide the agent reads. The server's instructions open with which tool does which job (where am I, read the edit, change it, find footage, hear, see, finish) and the one rule about analysis; the `guide` tool prints the manual a topic at a time (`guide sound` before the first music, `guide export` before an export), so the agent reads a thousand words when they matter and not eight thousand at the start; and `reference` in every `project-get` answer repeats the rules of the document. You never need to read it.

## What the agent can do

- **Read the video.** The tracks and clips, the media in use and which files have been analysed, the words spoken on a track with their timings.
- **Cut.** Every edit is a change to the document, from one trim to a whole new structure of named placeholders. Clip framing, levels, track settings, texts and caption bars are all keys in it.
- **Find footage.** `library-search` looks through everything your analysed media says (what happens, what is said, the words on screen, a song's tempo and drops, a sound's shape) and answers with files and the seconds that fit; `library` says what there is. See [Analysing footage](https://betteredits.app/docs/analysis).
- **Bring in footage.** `media-import` registers files with the video (copied in, or used in place from a media folder); `media-relink` points a missing file at another.
- **Make titles and graphics that move.** The agent writes a title, a caption bar, a callout or a takeover as a scene (`graphics-create`): elements with motions that the app lays out and draws itself on every frame, in the viewer and the export alike. Each is a small clip on a graphics track tied to the moment of footage it was made for, so a re-cut moves it and nothing is redone; a takeover hides the captions under it; the photos and frames of footage a scene shows are drawn from their files, so they stay HDR, and its type sits at the same white as the app's texts. To change what a graphic shows, ask the agent; it writes the scene again. When a scene cannot do it, the agent can still write a page of HTML and `alpha-clip-create` renders it into a clip with a transparent background, an ordinary clip on a video track that you move, trim and scale.
- **Caption.** `captions-generate` fills a subtitles track from the transcript; fixing a bar is an edit of the document. See [Captions](https://betteredits.app/docs/captions).
- **Look.** A frame or a contact sheet as a PNG, on disk for its pixels and read like any image (through the app's own render, the export pipeline or the viewer on screen), the geometry of a moment as numbers (`screen`, the person's face found in the frame), luma, contrast and a dim's edge margins measured off a frame (`measure`), and the loudness of a file over time; a quick preview export.
- **Show you.** Move the playhead, select a clip or a bar, show a file in Sources, play a file in the viewer, bring the app to the front.
- **Manage.** List and open videos, start one from a brief and a built-in structure, set up media folders, export.
- **Teach.** `getting-started` is the app explained for a person, which the agent reads and teaches step by step; it works before Pro is on.

What it cannot do: watch or listen to a file on its own. Every fact about footage comes from analysis, and the guide forbids guessing. It also cannot do anything the window cannot: no effects, no transitions, no speed changes. (Titles and graphics that move are the exception: the agent makes those as clips.)

![A contact sheet of eight labelled frames with the text and captions drawn on, made by BetterEdits so the model can look at the cut.](https://betteredits.app/screenshots/contact-sheet.png)

## Starter prompts

The server offers four prompts to any client that lists them; the Claude app shows them under the + menu by the server's name.

| Prompt                | What the agent does                                                                                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Getting started       | Reads `getting-started` and teaches the app: the workspace, videos and media folders, how it edits, what analysis is, and a first exercise that ends in an export |
| Cut the pauses        | Reads the transcript of the open video and cuts the pauses, leaving a little air                                                                                  |
| Caption it            | Waits for the analysis of what has no words yet, then fills a subtitles track                                                                                     |
| Build from my footage | Reads the analysed footage in a media folder and lays out a cut                                                                                                   |

## Prompts that work

> Read the transcript of Video 1, then cut out the pauses longer than a second. Leave a little air around each cut and show me a contact sheet when you are done.

> Add a title in the Strong favorite over the first two seconds that says "Stop doing this", near the top. Then put subtitles on the piece with the default style at the bottom.

> Start a new video called Hook v2 with three placeholders: hook, demo, call to action, five seconds each, with a music placeholder underneath.

> Read the analysed footage in the Footage folder and lay the clips where someone is talking to the camera on Video 1, in the order they were shot.

> Move the title so it starts on the second shot, and shorten every b-roll clip to two seconds. Show me a contact sheet.

Something with a transcript behind it works best: cut the pauses, caption it, turn a long recording into short clips. Judging a look does not; the agent sees frames, not motion.

> **Working alongside an agent**
>
> You need not watch: an agent works on a video in the background, and its card in the workspace window says so. Click the card, or ask the agent to show it, and its window opens on the work so far, every step in the undo history; while a window is up, every commit appears in the timeline as it lands. `seek` and `select` put the app on the moment it is talking about, and the detail in what it reads back is what it sees, so naming tracks and placeholders helps you both.

## Without Pro

The agent knows where this Mac stands: `status` carries it, the server's instructions say so, and a tool called without Pro answers with how to sign in or start the trial, which the agent relays and waits for. The first refused call is where most people meet the trial. See [Pro](https://betteredits.app/docs/pro#the-trial).