FAQ

Only questions the code can answer. Each one names where the answer comes from.

Installing and running

Do I need Node? No, to install. The wheel carries the compiled frontend as package data (web/**/* in api/pyproject.toml), and the build backend api/kotoba_build.py never runs npm — its own docstring says an install must not need Node. A CI job is written to prove it by installing the wheel with every Node directory stripped from the PATH, but that job has never run. You need Node 22 only to run the frontend dev server or rebuild the packaged UI from a clone. (.nvmrc, api/pyproject.toml, api/kotoba_build.py)

What Python version? 3.11 or newer. That is the declared floor and the only one; kotoba doctor refuses anything older. (api/pyproject.toml, requires-python)

Do I need an ElevenLabs key? For the voice, yes — the same key hears and speaks, in both voice modes. Without it she reads and writes perfectly well; she just does not speak. A free local speech engine is on the roadmap and no part of it is written yet. (README.md, ROADMAP.md, CHANGELOG.md)

Do I need Docker? No. KOTOBA_SANDBOX takes three values: local runs commands on the host behind the approval gate, docker runs them in a locked-down container, and none does not offer shell or execute_code at all. none is the strictest of the three, not the loosest. (SECURITY.md)

Which model providers? OpenAI and xAI are the two listed by name in api/src/kotoba/core/providers.py. Any endpoint that speaks the OpenAI Responses API also works — Settings takes a base URL and a model name typed by hand. Adding a provider by name, with its models and costs, is on the roadmap.

Does it work on Windows? setup, doctor, serve, discord and --once run natively. The interactive terminal session does not: it needs a POSIX terminal, and api/tests/conftest.py skips those tests on the product's own probe rather than on a platform string. Windows is in the CI matrix. (CHANGELOG.md, conftest.py, .github/workflows/ci.yml)

Does it send telemetry? No. SECURITY.md states it, ROADMAP.md lists telemetry under "not planned", and what leaves your machine is the model provider, ElevenLabs for voice, and whatever tool you asked her to use.

Where does my data live?

(SECURITY.md)

The repository

Why is there no Live2D model in the repository? Their licences forbid redistribution — Live2D's own free samples included. Committing one would republish somebody else's work under this repository's MIT licence. public/models/ is gitignored, models live in ~/.kotoba/models/, and scripts/build_web.py refuses to build if it finds one under public/. (CONTRIBUTING.md, THIRD_PARTY_NOTICES.md, .gitignore, scripts/build_web.py)

But Live2D code does ship? Yes, and it is allowed to. Cubism Core is redistributable by its own licence header, and the Cubism Web Framework travels compiled inside pixi-live2d-display. A runtime is not a model. See the licence page, including the revenue threshold that applies to redistributors.

Can I use Kotoba commercially? Yes. MIT, with no revenue clause and no non-commercial term. Ship the LICENSE file with it. The Live2D threshold in the notices file is a separate obligation and applies to redistributors above 10,000,000 JPY annual gross revenue.

Why does pytest not download anything? Because a stranger typing pytest must not make an outbound connection they did not ask for. Eight tests fetch and then run somebody else's package; they carry the network marker, are deselected by addopts, and are skipped a second time unless KOTOBA_ALLOW_NETWORK=1. The second lock exists because a -m typed on the command line replaces the first one. (api/pyproject.toml, pytest.ini, api/tests/conftest.py)

Why is there a pytest.ini and a [tool.pytest.ini_options]? pytest reads the pyproject.toml block only when api/ is the rootdir, so someone who clones and types pytest at the top would otherwise get no configuration at all — including no network deselection. The root pytest.ini repeats the three lines. If they disagree, api/pyproject.toml is right.

Is there a linter? No. There is no lint extra in api/pyproject.toml and no lint step in CI. Formatting is decided by .editorconfig: LF, UTF-8, 110 columns, 4-space Python, 2-space everything else.

What is api/src/kotoba/web/ and why is it empty in my clone? It is the compiled frontend, written by scripts/build_web.py, carried by the wheel and gitignored. A fresh clone has none, and nothing about a clone needs it — you run the dev server instead.

Why did build_web.py refuse to run? Most likely one of three: a .env-family file at the repository root (Next would inline it into the bundle), a Live2D model under public/, or no npm on PATH. It prints which. (scripts/build_web.py)

Why did it refuse after building? The scanner found your machine in the output — an address, a hostname, a home path, a tunnel URL, a source map, or image metadata. Do not add an allowlist entry; find the environment variable Next read. See the build pipeline.

I added a tool and she never uses it. It is almost certainly not registered. Importing the module is not registering it: a built-in must be named inside registry.discover(), an action tool inside ACTION_TOOLS. Nothing raises — the tool is simply offered to nobody. api/tests/test_no_tool_module_is_left_unregistered.py catches it.

Has any of the CI ever run? No. The workflow files exist; nothing has executed them. Treat every claim about CI as intent. See continuous integration.

Is there a released package on PyPI? Nothing has been published from this tree, and the Trusted Publishing arrangement the release workflow depends on has to be configured once on PyPI before a first release can go through. Nothing in the repository records whether it has been.

Contributing

What is the smallest useful contribution? A personality template in soul/templates/, or a model profile for another Live2D Cubism 4 model in lib/avatar-config.ts. Neither involves code. (CONTRIBUTING.md)

What must a pull request contain? What it changes, the command you ran and what it said, and a test that fails without the change. The template lists the four checkboxes: the backend suite, the frontend suite plus typecheck if anything under app/, components/ or lib/ moved, the web build if the packaged UI was touched, and no key, token, personal path or real name in the diff.

Can I put my name in a comment? No, and a test will stop you. api/tests/test_the_repository_belongs_to_nobody.py refuses home directories, real mailboxes, real account ids, and decisions credited to a named person. Say what was decided and why, not who asked. See the house rules.

How long can a comment be? Ten lines, for a comment or a docstring alike. Nothing enforces it automatically; a reviewer reads the diff.