# For Agents (Sashimii Docs, Reference)

> What an AI agent needs to help someone with Sashimii, the skill, the sashimii command-line tool, the project files, and the rules for changing them.

Canonical: https://sashimii.app/docs/for-agents/
Last updated: 2026-11-02

This page is for AI agents (Claude Code, Codex and others) helping a person use Sashimii, and for people who want to know what their agent does. The full drafting instructions ship with the app as the Sashimii skill; this page is the overview.

## The Skill and the Tool

- **The skill** is installed at `~/.claude/skills/sashimii/` (Claude Code) and `~/.agents/skills/sashimii/` (Codex) by **Sashimii › Install Command-Line Tool and Agent Skill…** in the app. Its `SKILL.md` and `references/` are the authoritative instructions: read them before drafting.
- **The command-line tool** is `sashimii`, linked at `~/.local/bin/sashimii`. If the shell can’t find `sashimii`, use `~/.local/bin/sashimii`, then `/Applications/Sashimii.app/Contents/Resources/sashimii`. If none exists, ask the person to run the install from the app’s Sashimii menu.
- `sashimii help` lists every command and flag.

When the person says “check Sashimii”, run `sashimii check`. It prints one JSON object whose `items` are what is waiting, newest first. Each item has a `kind`: `draft` (set up, no cut yet), `queue` (the person’s open notes, or graphics waiting for a retime), `busy` (another agent is working on it) or `style` (a Style request in the studio). It also has a `name`, `path`, `detail` and a `next` object (`action`, `message`, and `command` when there is one): do what `next` says. With nothing waiting, `next` says what to tell the person.

## Commands

| Command | What it does |
| --- | --- |
| `sashimii check [<project or folder> …]` | What is waiting for an agent, as JSON. Writes nothing. |
| `sashimii info <project>` | Summary of the project and its cut. Fails if a project file doesn’t parse. |
| `sashimii transcript <project> [<first id> <last id>]` | The transcript, one sentence per line with its source time and first and last word id, and every pause of 1 s or more. With two word ids, each word between them with its times. |
| `sashimii cut <project> <first id> <last id> <kind> <reason> […]` | Adds a removal for each cut named by its first and last word; works out the frames. `--dry-run` writes nothing. |
| `sashimii edges <project> [--no-pauses]` | Moves every cut edge onto the waveform, cuts pauses and wordless scraps, flags judgement calls. Run it last. |
| `sashimii pauses <project> [--min <seconds>] [--json]` | The silences and breaths in the kept material, for deciding pauses yourself. |
| `sashimii agent-done <project>` | Removes `agent.json`, so the app says the draft is ready. |
| `sashimii new <folder> [--video <name>] [--audio <name> \| --no-audio] [--style <name> \| --no-style] [--no-cleanup]` | Sets up a project from a folder, as the app does. |
| `sashimii cleanup <project> [--amount <0-100>] [--off]` | Turns voice cleanup on or off. |
| `sashimii render <project> <out.mp4> [--compatible] [--no-loudness] [--no-graphics]` | Renders a video project to MP4. One render at a time. A project with template graphics needs `--no-graphics`; the app renders those. |
| `sashimii export <project> --editor resolve [--out <bundle.fcpxmld>]` | Writes a DaVinci Resolve FCPXML bundle from the original media. |
| `sashimii export-wav <project> [--out <file>]` | Writes an audio project’s cut as a WAV. |
| `sashimii install-skill` | Links the tool and installs or updates the skill. |
| `sashimii register <claude-code\|codex\|manual>…` | Registers Sashimii’s server with an agent, or prints the commands. |
| `sashimii style …` | An agent’s side of the Style studio. See the skill’s `references/styles.md`. |

## Drafting a Rough Cut

The steps, in order (the skill has the detail):

1. `sashimii info "<project>"`. If the cut already has removals, ask before replacing them.
2. Write `agent.json` in the project: `{"agent": "<your name>", "task": "draft"}`. The app shows a banner while it exists.
3. Read the whole transcript with `sashimii transcript "<project>"`, to the last line, before deciding anything.
4. Choose the cuts by the person’s rules first, then the default take rules: keep the last clean, complete take; cut stumbles, restarts and asides; cut the head and tail; cut nothing for length; when unsure, keep it and write a note.
5. Write every cut in one `sashimii cut` command. Kinds: `retake`, `false-start`, `stumble`, `aside`, `other`. Then write a note in `notes.json` for each judgement call.
6. `sashimii info`, then `sashimii edges "<project>"` (with `--no-pauses` when the person wants pauses judged by their rules).
7. `sashimii agent-done "<project>"`, also if you stop early.
8. Report the length before and after, the removals by kind, and your notes in listening order.

## Project Files

A project is a `.sashimii` folder of JSON files beside the recording. Finder shows it as one file; agents and the tool see a folder.

| File | What it holds | Who writes it |
| --- | --- | --- |
| `sashimii.json` | The media, frame rate, sync offset, Style and cleanup settings | The app, setup and `sashimii cleanup` |
| `transcript.json` | Every word with its times | Setup only |
| `edit.json` | The removals: everything outside an active removal is kept | The agent (through `sashimii cut`) and the app |
| `notes.json` | Notes and directions, each with a range, tags, text and author | The agent and the app |
| `agent.json` | Which agent is working, while it works | The agent only |
| `graphics.json`, `graphics/` | Graphics and their bundles | The agent and the app |
| `cache/`, `drafts/` | Waveform, cleaned audio, the last 100 versions of each file, earlier drafts | The app and the tool |

Rules for changing them:

- **The recording is read-only**, and so are `transcript.json` and `sashimii.json`.
- **For a draft, write only `edit.json`, `notes.json` and `agent.json`.** Write `graphics.json` and `graphics/` only when asked for graphics or when the project has a Style.
- **Write each file whole.** The app may be open. Read the file just before changing it, keep every `id`, and replace the file. The app reloads it and keeps the person’s unsaved changes on top.
- **Run `sashimii info` after each write** to `edit.json` or `notes.json`. It fails on a file that doesn’t parse, and the app won’t save over a file it can’t read. It doesn’t read `graphics.json`; follow the skill’s `references/graphics.md` for checking those.
- **Notes:** `text` is one line under 100 characters, the call you made and the alternative. `by` is `"agent"`. Tags come from: `pip`, `text`, `broll`, `custom`, `fullscreen`, `halfscreen`, `karaoke`, `chapter`, `zoom`. A handled note gets `"done": {"at": "<ISO time>", "by": "<agent name>"}`.

## What Sashimii Doesn’t Do

So you don’t promise it to the person: Sashimii exports only to DaVinci Resolve (not Final Cut Pro or Premiere), doesn’t upload to YouTube, and has no pricing announced; the beta is free. Transcription and media processing run on the Mac, but the agent itself may send project information, including transcripts, to its provider.

## Reading These Docs as Markdown

Every page on this site has a Markdown version at its URL plus `.md`, for example [/docs/exporting.md](https://sashimii.app/docs/exporting.md). [/llms.txt](https://sashimii.app/llms.txt) lists every page; [/llms-full.txt](https://sashimii.app/llms-full.txt) has them all in one file; [/api/md/_catalog](https://sashimii.app/api/md/_catalog) lists them as JSON.

## Related

- [Keyboard Shortcuts](https://sashimii.app/docs/keyboard-shortcuts/)