HOW TO — 1 / 6
There are two entry points. If you are new, use the desktop app. If you already use Claude Code or Codex, use one command. Either way you end up with the same save data, so you can add the other later.
1 — Choose an entry point
| Entry point | Best for | How to get it |
|---|---|---|
| Desktop app macOS (Apple Silicon) / Windows (64-bit) |
First-timers, and anyone who wants to try it on screen first | Get the build for your OS from the download page (.dmg for Mac, .exe for Windows). → §2 on this page |
| Terminal (CLI) macOS / Windows / Linux |
People who already use Claude Code / Codex | One command installs it. → §4 on this page |
| From inside your usual agent Claude Code, Codex, opencode, Cursor Agent |
People who want to make videos from an agent session | In Claude Code, use /akari (you can install it as a plugin). Codex, opencode and Cursor Agent find the skills automatically, so just say “I want to start a new video project” |
Whichever you use, projects converge on the same save data (edit.json and .akari/). You can start in the app and add the CLI later, or the other way round, and pick up where you left off.
2 — Desktop app
The app is where you open, check and fix the edit the AI made. You can also talk to your AI partner inside the app. Get it from the download page.
| OS | What you download | Good to know |
|---|---|---|
| macOS Apple Silicon |
.dmg (a zip is also available) | Notarized by Apple. After opening it, move the app into the Applications folder before you use it (updates need this) |
| Windows 64-bit |
Installer .exe (a portable zip is also available) | The Windows build is not code-signed. On first launch, Windows SmartScreen may show a blue warning. Click “More info” → “Run anyway” to start it. The sha256 of each download is listed on Releases |
First you get a prompt to set up your workspace (where video projects live) and a guide for connecting an AI partner. You can connect later if you prefer. Then the app asks whether this is your first time using AKARI Video. Choose “first time” and the first-time guide starts (how to read the screen → add footage → ask the AI → export). Even before you connect an AI, you can play a demo to see the flow.
You can reopen the guide at any time from “Getting started guide” in Settings, or from “Replay the first guide” on the home screen.
ffmpeg and the transcription parts are bundled with the app. You don't need to install anything separately. The app also includes the akari command, so updating the app updates the CLI to the same version. (To use it from a terminal, add ~/.akari/cli/bin to your PATH, or use the installer in §4.)
3 — What you need
AKARI Video needs three things to run, and two of them are set up for you. All you decide is which AI partner (the brain of the edit) to use.
| What you need | What you do |
|---|---|
| Node.js v20+ The runtime that runs the CLI | Nothing — if it's missing, the installer places a portable copy in ~/.akari/. The app already includes it |
| ffmpeg Cutting, joining and exporting video | Nothing — bundled with the app. The CLI fetches the bundled build automatically (sha256 verified). If ffmpeg is on your PATH, that one is used instead |
| An AI partner The brain of the edit | Pick one from §5 below (Claude Code or Codex recommended) |
CLI supported OS: macOS, Windows, Linux (including WSL2). You don't need git for the macOS / Linux installer or for npm. Only the Windows installers (PowerShell / Command Prompt) require git: they clone the repository into %USERPROFILE%\akari-video. If you'd rather install without git, use the app or npm.
4 — Install (terminal route)
Open a terminal (PowerShell on Windows), paste the line for your OS and run it. If you use the app, you can skip this section.
curl -fsSL https://raw.githubusercontent.com/AkariLabs/akari-video/main/install.sh | bashirm https://raw.githubusercontent.com/AkariLabs/akari-video/main/install.ps1 | iexcurl -fsSL https://raw.githubusercontent.com/AkariLabs/akari-video/main/install.cmd -o install.cmd && install.cmdThe installer does the following:
~/.akari/app (you get a tested release, not a development branch)If you just want a light CLI install — npm i -g akari-video also works. It doesn't include the browser preview, though. For the full setup, use the installer above.
In the folder where you want to make a video (anywhere is fine), run:
# With Claude Code (default)
akari.sh
# With opencode
akari.sh --opencode
# Check the state of your setup
akari.sh doctorIf you installed with npm, the command is akari. If you see command not found, reopen your terminal.
On launch it checks whether the current location is a project. If it isn't set up yet, it walks you through creating an empty project, then starts your AI agent. After that, just talk to it, for example “I want to start a new video project”.
5 — Choose an AI partner
AKARI Video itself has no editing brain. The brain is an external AI partner, and whichever you use, it works on the same contract (files). In the app you connect it in the right-hand panel; in the CLI, the agent simply starts.
| Partner | Cost | Best for |
|---|---|---|
| Claude Code (recommended) | Paid (Claude subscription) | People who already use Claude, or who want higher edit quality |
| Codex (recommended) | Paid (ChatGPT subscription) | People who already use ChatGPT / Codex |
| opencode | Free models included | People who want to try it for free first |
| Cursor Agent | Cursor's pricing | People who prefer to work in the IDE chat |
| Muse Code (Meta) and others | Depends on each provider | People who already use one. Choose from those listed on the app's partner screen |
curl -fsSL https://claude.ai/install.sh | bash (see the official documentation)6 — Updates
When a new version comes out, it downloads in the background and gets ready to apply. It never restarts on its own while you're working. Your projects and videos are never deleted either (your data and the app itself live in different places → File map).
| Entry point | How it updates |
|---|---|
| App | The home screen shows “New version available — v○” and the download continues in the background. When it's done, press “Update and restart”, or choose “On next launch”. Your open project is already saved |
| CLI | It stays current just by being used. The update applies the next time you start akari, and one line says “Updated to vX.Y.Z”. To check by hand, run akari update |
Choose in Settings under “Release channel”. The default is “Stable only”. If you want new features early, choose “Include prereleases” and beta versions will reach you too. This setting also applies to automatic CLI updates.