Familiar-Connect

An AI "familiar" that joins Discord voice channels, listens, understands speech, and talks back with real AI voices.

Full documentation lives at docs/ — or browse the rendered site via uv run mkdocs serve.

Quickstart

uv sync --dev
cp .env.example .env                           # fill in your tokens
FAMILIAR_ID=aria uv run familiar-connect run

See Installation for prerequisites (libopus, Discord bot token, OpenRouter key, optional TTS / STT keys) and the env var reference. See On-disk layout for the minimum data/familiars/<id>/ shape.

Where things are

• Getting started — install, run, troubleshoot.
• Architecture — the bot shell, configuration model, security, design decisions.
• Contributing — dev workflow, TDD expectations, docs build.

Development commands

uv sync --dev                 # install + dev deps
uv run ruff check             # lint
uv run ruff format            # format
uv run ty check               # type-check
uv run pytest                 # run tests
uv run mkdocs serve           # preview the docs site