How an agent edits

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; the setup is on Connect an 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.
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.
• 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.
• 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.)

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.

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.

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.