# Claude Code

> The guide the app writes into every workspace, what Claude Code can do there, and how it relates to the command line.

## What the app sets up

Every workspace carries three things for Claude Code. The app writes them when it creates the workspace and refreshes them on every launch.

| File                    | What it is                                                                                                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BetterEdits.md`        | The generated guide: how to run the command line, every command with its options, and how tracks, clips, text and captions behave. Rewritten on every launch, so keep your own notes out of it. |
| `CLAUDE.md`             | Yours. The starter imports the guide with `@BetterEdits.md` and records the workspace's canvas, media folders and where exports go. Add anything you want Claude to know about your videos.     |
| `.claude/settings.json` | A permission rule that lets Claude run the app's command line without asking each time. Other rules in the file are kept.                                                                       |

The command line is the app's own binary, `/Applications/BetterEdits.app/Contents/MacOS/BetterEdits cli …`. Nothing goes on your PATH and nothing is copied anywhere. If the app moves, the next launch rewrites the guide and the rule with the new path.

## Start a session

Open a terminal in the workspace folder and start Claude Code.

```
cd ~/Movies/Reels
claude
```

Claude reads `CLAUDE.md`, follows the import to the guide, and can then drive the app. Commands connect to the running app; if it is not running they launch it in the background.

## What Claude Code can do

Edit the files, or run the commands; both land in the app live. A project is three JSON files written for reading (see [Workspace](https://betteredits.app/docs/workspace)). The loop the guide teaches: read `project.json` and `timeline.json`; read the analysis next to the footage when there is one, else look with `contact-sheet --path` and `levels`; write the edit in one go; `lint` it (every problem and warning at once, no app needed) and `sync` to hear that the app took it; then look with `contact-sheet --clips`, `frame` or `export --preview`. The commands do single precise steps through the editor's rules. See [Command line](https://betteredits.app/docs/cli). In practice:

- Read the project: which tracks and clips exist, the media in use and which files have been analysed, the words spoken on a track with timings (from those files; Claude reads them whole for the rest of what they hold: scenes, cuts, silences, beats).
- Cut: add, trim, split, move, replace and remove clips; add placeholders; put text on screen; add and fix captions; change styles and positions.
- Look: render a frame or a contact sheet as a PNG and read it like any image; make a quick preview export.
- Show you: move the playhead, select a clip, bring the app to the front.
- Manage: list and open projects, set up media folders, import a template, export.

Every change lands in the app as an ordinary undo step. You see it in the timeline as it happens, and ⌘Z takes it back.

## Analysing footage

Claude cannot watch a video. What it knows about a file beyond its length comes from analysing it once: `analyze <file>` sends the file to the analysis service and writes `<file>.analyzemedia` next to it, with every spoken word and its timing, speakers, on-screen text, scenes and silences. The guide tells Claude to check `media` for `words` before cutting by what was said, and to run `analyze` on any file that has none. You never type the command.

Analysis is part of Pro, which starts with a 7-day free trial. The first session goes like this:

> Cut the pauses longer than a second out of take-3 and caption it.

Claude reads the project and sees that `take-3.mov` has no words, and that this Mac is not signed in. It runs `login`, which opens the dashboard in your browser, and asks you to approve the sign-in there. You sign up, start the trial (card on file, nothing charged for seven days), and the page says the Mac is connected. Claude sees it, runs `analyze`, waits, and says what it found and what is left on the balance. Then it cuts.

The credential is kept in the app's own settings, never in a workspace; the dashboard lists every linked Mac and can sign one out, and the account badge in the app shows the plan and the credit. Without Pro, `analyze` and the other commands answer with the link to start it; when the credit runs out, `analyze` fails with the amount the job needs and the link to buy more. Claude relays the link and waits for you to say it is done. `account` prints the plan and the balance at any time.

Footage that has not been analysed is never refused: it plays, cuts and exports as usual. Claude can still cut it by time and look at its frames with `contact-sheet --path`; it just cannot cut it by what was said.

## 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.

> Here is a template for a three-shot reel: hook, demo, call to action, each five seconds, with music underneath. Write the JSON, import it as a new project called Hook v2, and open it.

> 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.

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

> **Working alongside Claude**
>
> Keep the project window open while Claude edits. `seek` and `select` put the app on the moment Claude is talking about, and the level of detail in `timeline` is what Claude sees, so naming tracks and placeholders helps you both.

## Claude Desktop, Cursor and other MCP clients

The same tools are an MCP server. Settings › Agent integration adds it with one click to Claude Code, Claude Desktop and Cursor; any other client takes the command it shows, the app's own binary with `mcp` after it. The workspace guide arrives as the server's instructions, so nothing needs to be in the folder, and relative paths resolve against the workspace that is open in the app. Agent integration is part of Pro; a call without it answers with how to sign in or start the trial.

For Claude Code by hand:

```
claude mcp add --scope user betteredits -- /Applications/BetterEdits.app/Contents/MacOS/BetterEdits mcp
```