# Use a coding agent

Give a coding agent a Yapwing project and the local `yapwing` command. Claude
Code, Codex, OpenCode and other tools that can run commands use the same
command.

## Set up the command

Install the [Mac preview](https://yapwing.com). In the app, choose
**Help → Use with Coding Agents…**. The sheet has a row for each setup:

- **Claude Code** installs the editing skill for every project.
- **Claude Code, one project** installs it in a folder you choose.
- **Codex** installs it for Codex.
- **Command line** links the app's CLI to `~/.local/bin/yapwing`. It does not
  ask for a password.

The skill teaches the agent the editing rules on this page. Other agents can
run the CLI directly.

Check the command from a terminal your agent can use:

```sh
yapwing inspect /absolute/My-video.yapwing
```

Replace the path with your saved project folder. A successful response has
`ok: true` and a `value` containing its `snapshot` and `statuses`. Inspect
before making an edit. The project can be open in the app: the command sends
its edit to the app instead of writing a second copy behind it.

## Make an edit by sentence

Export a readable view to a separate file:

```sh
yapwing view /absolute/My-video.yapwing > /absolute/edit.yapwing.ts
```

Ask the agent to keep the `clip()` structure and edit the `say()` lines for
the passage you want. The file is a restricted data format with TypeScript
syntax. Yapwing parses it; it never executes JavaScript.

Validate the edit, then apply that same file:

```sh
yapwing edit /absolute/My-video.yapwing --file /absolute/edit.yapwing.ts --dry-run
yapwing edit /absolute/My-video.yapwing --file /absolute/edit.yapwing.ts
```

Play across the change in the app. It is one **Agent Edit** undo step. A file
made from an older revision is refused; view the project again and redo the
change.

For a small change, write operation calls instead of the whole file and add
`--ops`:

```sh
printf '%s\n' 'cut_fillers()' 'fix("s6", "flower", "flour")' > /absolute/ops.ts
yapwing edit /absolute/My-video.yapwing --ops --file /absolute/ops.ts
```

[Agent requests and recovery](/docs/agent-requests#view-and-edit) describes the
operations.

## Use exact commands

For clip, word and caption operations, use JSON requests through
`yapwing check` and `yapwing apply`. Each request names the inspected project,
its expected revision and a stable operation ID. Keep the complete request
until the result is known. After an uncertain response, retry that exact
request with the same operation ID; changing its payload is refused.

The [CLI reference](/docs/cli) lists the commands. The
[project and command format](/docs/project-format) defines request fields and
the reply shape. [Agent requests and recovery](/docs/agent-requests) covers batching, collection,
source analysis and recovery.

## Check the result

```sh
yapwing preview /absolute/My-video.yapwing --range s3-s5 --frames 4 --audio
```

The reply lists JPEG stills and an audio snippet of that range in a new
temporary folder. The agent can read the stills to check framing and captions.
Preview never changes the project.

## Interface availability

The bundled CLI and the skill are included in the downloadable preview. A
[TypeScript source SDK](/docs/sdk) wraps the CLI for code with access
to the private SDK source. It is not a public npm package.

External agents follow their own model and data settings, so choose the
project access you give them.

## Connect over MCP

Choose **Help → Use with Coding Agents…**, then **Copy** beside Claude Code or
Codex under **Connect over MCP**, and paste the command in Terminal once. It
adds the `yapwing` helper inside the app as a stdio MCP server:

```sh
claude mcp add yapwing -- '/Applications/Yapwing.app/Contents/Helpers/yapwing' mcp
codex mcp add yapwing -- '/Applications/Yapwing.app/Contents/Helpers/yapwing' mcp
```

The copied command names the location of your Yapwing. The agent starts the
helper itself, and the helper passes each tool call to the open app on this
Mac. There is no port or token, so the entry keeps working after you reopen
Yapwing; copy it again only if you move the app.

The agent then has the tools `inspect`, `view`, `edit`, `check`, `apply`,
`preview`, `library`, `search` and `export`, on the project open in the app.
They return what the matching `yapwing` command prints.

| Error | Meaning | Recovery |
| --- | --- | --- |
| `app_not_open` | Yapwing is not running. The agent can list the tools, and each call fails. | Open Yapwing, then retry. |
| `no_project` | Yapwing is running with no project open. | Open a project in Yapwing, then retry. |

### Over HTTP

The sheet's **Over HTTP** menu instead copies an address and token for this
launch only. Use it for a client that can't start a command:
`claude mcp add --transport http yapwing http://127.0.0.1:PORT/mcp --header "Authorization: Bearer TOKEN"`,
or for Codex an export of `YAPWING_MCP_TOKEN` followed by
`codex mcp add yapwing --url … --bearer-token-env-var YAPWING_MCP_TOKEN`; run
that in the Terminal window where you start Codex. The address and token change
every time Yapwing opens, so copy again after reopening (for Claude Code, run
`claude mcp remove yapwing` first). The sheet never shows the token, and Claude
Code saves it in its own configuration.