Connect your AI partner (VS Code / Terminal)

Once Claude is connected to Akari, you can control each app — Video / SVG / Sheets / Stage / Design / 3D — by conversation. Ask "cut this video" or "turn this table into a chart," and the AI actually performs the edit. This guide walks a first-timer through connecting Akari and Claude (i.e. completing Partner Connect). There are two ways to connect, and both work the same: • Use it from the VS Code extension (Claude Code) • Use it from the terminal with the claude command No Akari account, token entry, or API key is required on the Akari side. The only login you need is signing in to Claude itself.

• A Mac (Apple Silicon / M1 or later) • A Claude account (Claude Pro / Max, or an API key) — used to sign in to Claude Code • About 10 minutes Key point: the only thing you log into is Claude. The token used for the Akari bridge is generated automatically on your machine the first time you launch Akari (~/.akari/secrets/mcp-bridge-token), and the rest of the setup is automatic too. You never copy a token by hand. All traffic stays on 127.0.0.1 (your own computer) and is never exposed externally.

Without Akari itself there is no "endpoint" to connect to, so install the app first. 1. Get the Akari installer (macOS / Apple Silicon) from the download page. 2. Open the downloaded DMG and drag Akari.app into Applications. 3. Double-click /Applications/Akari.app to launch it. On launch, the local connection token is generated automatically. Each app's "window" (its MCP server) starts automatically the moment you open that app inside Akari. No separate start command is needed.

1. Install VS Code (code.visualstudio.com). 2. Install Claude Code — either way is fine: • Search for "Claude Code" in the VS Code Extensions panel and install it • Or in a terminal: npm install -g @anthropic-ai/claude-code 3. Sign in to Claude (this is the "authentication" step). • Extension: sign in from the Claude panel in the sidebar • Terminal: run claude, then /login The only sign-in here is to Claude itself. No Akari-specific authentication appears.

On the Akari side, generate the configuration that wires you up to Claude. 1. In Akari, open the app you want to control once (e.g. Video). ← This starts that app's window. 2. Open Settings → Partner Connect (パートナー接続). 3. "Which AI?" → Use Claude / "Where?" → In my own terminal. 4. Click "Start setup" and pick the project folder you'll use with Claude. Akari writes CLAUDE.md and .mcp.json into that folder (existing files are backed up automatically). The .mcp.json connects to Akari through a local proxy, and the auth token is attached internally. You never handle the token by hand.

Just open the folder Partner Connect set up, whichever way you prefer. A. From VS Code 1. Open the folder you picked in VS Code (File → Open Folder). 2. The Claude Code extension reads the folder's .mcp.json automatically. The first time, it asks "Use the MCP servers for this project?" — approve it. 3. Talk to Claude, and Akari's tools (video_*, etc.) are available. B. From the terminal 1. cd into that folder and run claude. 2. It reads the same .mcp.json and connects to Akari. To verify: run /mcp inside Claude, or claude mcp list in the terminal. If akari-os shows up, you're connected. If you haven't opened the app in Akari yet, you may see "can't connect." Open that app in Akari and it connects automatically.

Instead of Partner Connect, you can connect to each app's window yourself, registering each port with the token. # Load the token into a variable TOKEN="$(cat ~/.akari/secrets/mcp-bridge-token)" # OS layer (open / switch apps) + the apps you use claude mcp add --transport http akari-shell http://127.0.0.1:47628/mcp --header "Authorization: Bearer $TOKEN" claude mcp add --transport http akari-video http://127.0.0.1:47616/mcp --header "Authorization: Bearer $TOKEN" # others: svg=47618 / sheets=47620 / stage=47622 / design=47624 / 3d=47626 / diagram=47630 / fx=47632 / synth=47634 Add -s user to register for every project. Check with claude mcp list. For the full port list and how it all works, see the "Control with AI (Codex / Claude)" guide.

From here, just ask in plain language. The trick is to first ask it to "look at the current state" (so the AI understands things before editing). • "Look at the state of the app I have open" • Video: "Cut the silence at the start" / "Add subtitles" • SVG: "Draw an icon: a rounded square with a star on top" • Sheets: "Turn this table into a bar chart, in blue" • Stage: "Place an iPhone in the center and rotate it slowly" Everything the AI does is mirrored on the Akari screen, and you can undo it.

• "Not connected / timeout / Failed to connect" → Check the app is open inside Akari. Open it and it connects automatically. • MCP tools don't appear in VS Code → Make sure you used "Open Folder" on the folder that has .mcp.json, and that you approved using the MCP servers. • 401 / 403 / Unauthorized → Token mismatch. Re-run Partner Connect to regenerate .mcp.json (for manual setups, re-copy ~/.akari/secrets/mcp-bridge-token). • Not sure what's possible → Ask Claude to "list the available tools" (it always returns the latest).