HOW TO — 5 / 6

Use from Claude Code / Codex

If you already use an AI agent, AKARI Video adds video production to that agent's capabilities. There is no dedicated API: files are the only connection. Your editing brain can be Claude Code, Codex, opencode, Cursor, or any agent that comes next.

Last updated 2026-08-10 AKARI Video v0.1.6

1 — The idea

`edit.json` is the source of truth. The app is a lens onto it

All editing state lives in edit.json at the project root, alongside captions.json for subtitles and review.json for reviews. The viewer, renderer, and agent all work by reading and writing these files.

Works well with git — Every edit is a text diff. Branching and reverting work too
No lock-in — With plain files as the source of truth, your work survives a change of tools
Use any entry point — The terminal, app, and any agent all converge on the same state

2 — Entry points

Call it from your usual session

Harness	How to invoke it
Claude Code	Use `/akari` to check the current location and get the next step, or say “I want to create a new video project”
Codex CLI	Open the repository or project to discover skills automatically from `.codex/skills/`. Use the same prompt
opencode	Say “I want to create a new video project” to trigger the create-project skill
Cursor Agent	Open the project in Cursor to discover skills automatically from `.cursor/skills/`. Use the same prompt

CLI subcommands

akari.sh              # Launch the AI agent (Claude Code preferred)
akari.sh --opencode   # Launch with opencode
akari.sh --preview    # Preview server (http://localhost:4567)
akari.sh update       # Check for updates

If you prefer npm, npm i -g akari-video installs the akari command (without the browser preview).

3 — Skill list

One skill per stage, 21 in total

The workflow is divided into 21 skills. The appropriate skill usually activates from your request, but you can also invoke it explicitly. Each SKILL.md (listed in the GitHub skill catalog) is the source of truth.

Stage	Skill	Responsibility
Planning	research-plan	Ideas → research → proposal, outline, storyboard, and shot list
Preparation	create-project	Create a project by copying the template
	setup-library	First-time setup: check tools → get a starter pack
	setup-audio-library	Semi-automated music and SFX library intake
	declare-audio	Listen and mark choruses, accents, and beats → declarations.json (read by automatic music suggestions)
	setup-remote	Remote setup via Tailscale, without public internet exposure
	harvest-asset	Add high-cost project outputs to the reusable asset library
	bake-3d	Bake 3D scenes into video assets with Blender
	beat-sync-edit	Generate beat-snapped edits using declared beats and accents as the timing source (promos and showcases)
	manage-connections	Centralize API connections, model selection, and cost approvals (the sole entry point for paid generation)
Analysis	analyze-footage	Analyze one source video: proxy, transcript, and keyframes
Analysis	analyze-project	Interpret material across source videos and produce a read-only report
Editing	edit-plan	Finalize the plan with explicit approval → edit.json and overlays
	overlay-authoring	Author telops, subtitles, charts, 3D, and motion graphics
	generate-narration	Script → narration audio (VOICEVOX and other engines)
QA / review	edit-lint	Deterministic editing-data checks (the gate before export)
	compile-review-session	Transcribe recorded reviews → turn them into revision tickets
	address-review	Follow the ticket workflow: implement fixes → check → update tickets
Export	render-cut	Create the final MP4 from approved edit.json using local ffmpeg
Export	export-nle	Export to other editors (BETA → §4)
Development	verify	Run the task contract's verification levels (for contributors)

4 — Export to other editors

Export to Premiere / Final Cut / Resolve

BETAImport into actual NLE applications has not yet been verified. Output follows the format specifications. If it does not import in your environment, let us know via Issues.

This is a one-way export for finishing AI-assembled edits in your preferred editor. Changes made there do not return to AKARI Video:

.fcpxml — For Final Cut Pro / DaVinci Resolve
.xml(FCP7 XML format) — For Premiere Pro
.srt — Subtitles (when captions.json exists)
Elements that could not be transferred are explicitly listed in dropped[] in export-report.json; nothing is silently omitted

Specification source of truth: export-nle contract (GitHub)

5 — Go deeper

All data contracts are public

The edit.json schema, project structure, preview/renderer parity guarantees, and asset library conventions are all documented in docs/ on GitHub. Give a contract to your agent and ask it to read it: it becomes a foundation for extensions and automation.