miku-discord/AGENTS.md

AGENTS.md

Language & runtime

• Python 3.11 (main bot). There is no root package.json or TypeScript — do not apply Node/TS tooling.
• uno-online/ is a secondary Node.js project; miku-app/ is Android/Kotlin. Both shelved features for now.

Commands

# Build and run all core services (bot, STT, llama-swap, Cheshire Cat, Qdrant)
docker compose up -d

# Run with face-detector (requires NVIDIA GPU)
docker compose --profile tools up -d

# Run only the bot (implies dependencies are already up)
docker compose up -d miku-bot

# View bot logs
docker compose logs -f miku-bot

# Rebuild bot after code changes
docker compose down miku-bot && docker compose build miku-bot && docker compose up -d miku-bot

Config

• config.yaml: app settings (model names, URLs, ports, feature flags).
• .env: secrets only (DISCORD_BOT_TOKEN, OWNER_USER_ID, ERROR_WEBHOOK_URL).
• Config is loaded by bot/config.py (Pydantic) and bot/globals.py (bare os.getenv). Both sources matter — check both when tracing config usage.
• Runtime config overrides are persisted to bot/memory/config_runtime.yaml via the API.

Architecture

Discord <-> bot/bot.py (discord.py)
               ├── on_message -> Cheshire Cat pipeline -> memory-augmented LLM response
               ├── utils/llm.py -> llama-swap (HTTP proxy) -> llama.cpp (NVIDIA or AMD GPU)
               ├── utils/voice_manager.py -> STT WebSocket (port 8766) and audio playback
               ├── FastAPI (port 3939, daemon thread) -> 22 route modules in bot/routes/
               ├── APScheduler (background tasks in globals.py)
               └── utils/autonomous_engine.py -> proactive message decisions (Autonomous V2)

• The FastAPI server runs in a daemon thread inside the Discord bot process — no separate process.
• bot/globals.py holds mutable global state (scheduler, env vars, discord.Client). Module-level mutations are pervasive; be careful with import order.
• llama-swap is a llama.cpp HTTP proxy with TTL-based model swapping. Two configs: llama-swap-config.yaml (NVIDIA) and llama-swap-rocm-config.yaml (AMD).

Models (via llama-swap)

Model key	Purpose
llama3.1	Primary text model
darkidol	Uncensored model (evil mode)
vision	MiniCPM-V (image understanding)
swallow	Japanese text model
rocinante	12B model (AMD GPU only)
qwen3.5	ComfyUI prompt generation (AMD GPU only)

Testing & linting

• No formal test framework and no linting/formatting config. Ad-hoc scripts live in tests/ and bot/tests/.
• Run ad-hoc tests however you want; there is no standard command.

Web UI color scheme (bot/static/)

• Base: #121212 body, #000 log panel, #1e1e1e code blocks, #2a2a2a cards
• Text: #fff primary, #ccc labels, #888 muted, #0f0 log info
• Primary accent: #61dafb (headings, links, assistant messages, active elements)
• Success: #4CAF50 (active tabs, user messages, enabled toggles)
• Error: #f44336 (chat errors), #ff6b6b (error logs)
• Warning: #ffd93d (warning logs)
• Bot message: #2196F3 (left border)
• Danger/evil: #ff4444 (overrides all accents when body.evil-mode is set)
• Bipolar: #9932CC (toggle active)
• Blocked: #ff9800 (blocked user cards)
• Evil mode toggles body.evil-mode class which replaces all #61dafb and #4CAF50 with #ff4444.

Key gotchas

• bot/memory/ contains persisted JSON state files and is gitignored. Do not expect these to exist in a fresh clone.
• .env is gitignored; copy .env.example to .env and fill in real tokens.
• Changes to bot/moods/ or bot/persona/ text files take effect at runtime (loaded on demand), no rebuild needed.
• Playwright browsers must be installed in the Docker image (bot/Dockerfile does this via setup_uno_playwright.sh).
• Voice features require discord-ext-voice-recv and PyNaCl — if voice fails, check these are installed.
• The miku-voice Docker network is declared as external — it must exist before docker compose up.