Requirements

Two of these are awkward and get stated first, because finding them out after you have installed is worse.

An ElevenLabs account is required for the voice

There is no local speech engine. The whole voice path — hearing you and speaking back — goes to ElevenLabs, in both voice modes.

• local mode (the default). Your browser streams microphone audio to your own backend over a WebSocket, and your backend calls ElevenLabs for transcription and for speech. One API key does both. Every connection is outbound; nothing has to reach in.
• agent mode (optional). ElevenLabs' Conversational AI platform runs the call itself, so you need an account and an agent configured in their dashboard — and their cloud has to be able to reach your backend at a public URL, because in that mode they are the one calling you.

Without a key, everything except sound works. She reads, writes, thinks, runs tools, remembers, and answers you in the browser and in the terminal. kotoba doctor reports a missing voice key as a warning, not a failure, and the setup wizard lets you skip it.

Keys are made at https://elevenlabs.io/app/settings/api-keys. The environment variable is ELEVENLABS_API_KEY, though the normal way is to paste it during kotoba setup, which stores it encrypted rather than in a file.

A free local voice is on the roadmap and no part of it is written yet.

No Live2D model ships with Kotoba

The good Cubism models — including Live2D's own free samples — are licensed in a way that forbids redistribution, so the repository carries none and never will. The face arrives on your machine from its author instead.

Three ways to get one:

1. The browser's first-run screen fetches Live2D's free sample for you. It shows the licence link first and only downloads after you accept. The sample is niziiro-mao, about 74 MB, fetched from cubism.live2d.com.
2. Upload a .zip you already have, on the same screen.
3. Unpack a Cubism 4 model by hand into its own folder under ~/.kotoba/models/, then reload the page.

kotoba setup in a terminal does not offer this — there is no browser there to show the licence in. A terminal-only install therefore finishes with no face. The first time you open the app after that, it sends you once to the face step to close the gap.

Everything else works without a model. The app runs, the voice call runs, the agent runs; the avatar area shows a notice naming the folder to put a model in.

Everything else

Optional pieces that change what she can do rather than whether she runs — kotoba doctor names each one and what its absence costs:

• Node on your PATH — MCP servers launched through npx cannot start without it.
• A Chromium-family browser — needed for report PDFs and for browser automation.
• ripgrep (rg) — without it, file search drops to a literal, non-regex scan.
• chafa — draws the sharpest terminal portrait. Without it she falls back to half-blocks. doctor does not check for this one.

Which model to pick

kotoba setup lists the models it offers cheapest first and tells you what each costs relative to the cheapest. At the time of writing it offers seven OpenAI models, with gpt-5.6-luna as the default and the cheapest, and three xAI models with grok-4.3 as the default. You can also type any other model id belonging to your provider; the wizard says plainly that it has not checked that one.

Next: Installing.