Installing

Kotoba is one Python package, kotoba-companion. It needs Python 3.11 or newer and nothing else.

pip install "kotoba-companion[server,voice,cli,web,mcp]"

That gives you everything except the Discord bot. Then:

kotoba setup     # pick a provider, hand over a key
kotoba serve     # backend + web UI; the address is printed

Use a virtual environment if you would rather not install into your system Python:

python -m venv kotoba-env
source kotoba-env/bin/activate        # Windows: kotoba-env\Scripts\activate
pip install "kotoba-companion[server,voice,cli,web,mcp]"

Each release also attaches the built wheel and source archive to its GitHub release page, so you can install a specific version from a downloaded file:

pip install "./kotoba_companion-<version>-py3-none-any.whl[server,voice,cli,web,mcp]"

The extras, and what each one is for

The base package is the engine: the agentic loop, the tools, memory, the encrypted keystore. It runs a full turn with no HTTP server at all. Everything else is an extra.

The first five "without it" lines are not editorial: they are the sentences kotoba doctor prints for that missing extra, alongside the exact pip install command that adds it. discord and dev are not on doctor's list.

Install web. It is the one whose absence quietly changes where your data goes: web_extract falls back to the r.jina.ai reader service, which means every page she reads for you is fetched by somebody else.

Add Discord later with pip install "kotoba-companion[discord]".

What a bare install can still do

pip install kotoba-companion with no extras is a legitimate install. Measured, it gives you:

• kotoba setup — the same wizard, in plain text with no chrome
• kotoba doctor — the full report
• kotoba --once "…" — one question, one answer

kotoba on its own prints pip install "kotoba-companion[cli]" and exits 1. kotoba serve names kotoba-companion[server] the same way. Neither crashes.

The web UI needs no Node

This is worth explaining, because it is unusual for a project with a React frontend.

The Next.js app is compiled before the package is built, by a script in the repository, and the result is copied into the Python package as kotoba/web/. It ships inside the wheel as ordinary package data. Installing therefore never runs npm — the package's build backend is a wrapper that only verifies the compiled UI is present, current and stamped for the same version, and refuses to build a distribution otherwise.

At run time the backend serves those files itself, from its own port, at /app. kotoba doctor reports which UI you have under web ui; on a plain install it looks like this, with the real file count and version:

ok    web ui      packaged build, 69 files, kotoba 0.10.0 — `kotoba serve`, then /app

The build refuses to run if a .env or .env.local file exists at the repository root, because Next inlines any NEXT_PUBLIC_* value it finds and one machine's address would be frozen into everyone's copy. It also scans the finished build for private hostnames, IP literals, tunnel domains, home directory paths, source maps and image metadata, and refuses if it finds any.

One consequence: you cannot pip install straight from a git checkout of the repository. A fresh clone does not contain the compiled UI — it is deliberately not committed — so building a wheel from it stops with:

refusing to build the wheel: the packaged web UI is absent or stale.
  - .../src/kotoba/web does not exist
  build it first:  python scripts/build_web.py   (needs Node)

Editable installs are exempt, which is why working from a clone still works. See Installing from a clone.

Check the install

kotoba --version
kotoba doctor

doctor exits 0 when she can run and 1 when something must be fixed first. Every row is explained in kotoba doctor.

Next: First run.