For Agents

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. /llms.txt lists every page; /llms-full.txt has them all in one file; /api/md/_catalog lists them as JSON.