Koko210/miku-discord
1
0
Fork 0
Code Issues 34 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8ca716029e95a997d3d2b8b3a454a3aae4738a30
miku-discord/readmes/COMMANDS.md
koko210Serve c708770266 reorganize: consolidate all documentation into readmes/ 
- Moved 20 root-level markdown files to readmes/
- Includes COMMANDS.md, CONFIG_README.md, all UNO docs, all completion reports
- Added new: MEMORY_EDITOR_FEATURE.md, MEMORY_EDITOR_ESCAPING_FIX.md,
  CONFIG_SOURCES_ANALYSIS.md, MCP_TOOL_CALLING_ANALYSIS.md, and others
- Root directory is now clean of documentation clutter
2026-03-04 00:19:49 +02:00

28 KiB
Raw Blame History

Miku Discord Bot — Commands & Features Reference

Last updated: February 18, 2026

Comprehensive documentation of every Discord command, API endpoint, and feature in the Miku bot.

Table of Contents

Discord Commands

Voice Commands (!miku)

All voice commands are prefixed with !miku and must be used in a server (not DMs).

Command Arguments Description File
!miku join [#channel] Join the user's voice channel (or the mentioned channel). Locks GPU resources for voice. bot/commands/voice.py ~L57
!miku leave — Leave the current voice channel and release all resources. bot/commands/voice.py ~L131
!miku voice-status — Show current voice session status, resource allocation, and active features. bot/commands/voice.py ~L168
!miku test [text] Test TTS audio playback with custom or default text. bot/commands/voice.py ~L252
!miku say <message> Send a message to the LLM, speak the response in voice chat. bot/commands/voice.py ~L284
!miku listen [@user] Start listening to a user's voice via STT (defaults to command author). bot/commands/voice.py ~L381
!miku stop-listening [@user] Stop listening to a user's voice (defaults to command author). bot/commands/voice.py ~L431

Permissions required: Bot needs Connect and Speak permissions in the target voice channel.

UNO Commands (!uno)

Miku can play UNO card games as Player 2, controlled via a Playwright browser automation.

Command Arguments Description File
!uno join <room_code> Join an existing UNO game room as Player 2. bot/commands/uno.py ~L25
!uno list — List all active UNO games Miku is playing. bot/commands/uno.py ~L82
!uno quit [room_code] Quit a specific game (or all games if no code provided). bot/commands/uno.py ~L106
!uno help — Show UNO command help and how to play. bot/commands/uno.py ~L158

No special permissions required. Miku uses AI to make strategic moves and trash-talks during games.

Inline / Special Commands

These are handled directly in the on_message handler in bot/bot.py:

Command / Trigger Description File
!monday Manually trigger the Monday video feature. Server messages only. bot/bot.py ~L708
miku, rape this nigga balls Must be a reply to another message. Overlays the replied-to user's name on the MikuMikuBeam.mp4 video and sends it as a reply. Easter egg command. bot/bot.py ~L196

Conversational Features

Addressing Miku

Miku responds when she detects she is being addressed. The detection logic is in bot/utils/core.py (is_miku_addressed).

Miku will respond when:

  • In DMs: Always responds to every message.
  • @Mentioned in a server channel.
  • Replying to one of Miku's messages.
  • Her name is mentioned — supports multiple scripts:
    • Latin: miku
    • Cyrillic: мику
    • Hiragana: みく
    • Katakana: ミク
    • Kanji: 未来
    • Plus any combination with Japanese honorifics (-chan, -san, -kun, -nyan, -senpai, etc.) in all scripts.

Direct Messages (DMs)

  • Any user can DM Miku directly and get a response.
  • DMs use the global DM_MOOD (auto-rotating) instead of per-server moods.
  • All DM conversations are logged for the admin Web UI.
  • Users can be blocked from DMs via the API.
  • The bot logs reactions added/removed in DM conversations.

Media Analysis

When a user sends media while addressing Miku, she analyzes it with the vision model:

Media Type Supported Formats Description
Images .jpg, .jpeg, .png, .webp Analyzed by Qwen vision model, then rephrased as Miku
Videos .mp4, .webm, .mov Frames extracted, analyzed by vision model
GIFs .gif Converted to MP4, frames extracted, analyzed
Tenor GIFs Discord /gif embeds Extracted from Tenor URLs, processed as GIFs
Rich embeds Articles, images, videos, links Text extracted and images/videos analyzed

All media analysis is blocked during active voice sessions.

Image Generation

Miku can generate images using ComfyUI when users make natural language requests. Detection is pattern-based in bot/utils/image_generation.py.

Trigger phrases include:

  • "draw me a picture of..."
  • "generate an image of..."
  • "show me yourself swimming"
  • "can you paint..."
  • "I want to see you..."
  • "what do you look like?"

Image generation is blocked during voice sessions.

Kindness Reactions

Defined in bot/utils/kindness.py. When users say kind things to Miku, she reacts with a heart emoji.

Keyword triggers: "thank you", "love you", "luv u", "you're the best", "so cute", "adorable", "amazing", "sweet", "kind", "great job", "well done", "precious", "good girl", "cutie", "angel", "my favorite", "so helpful"

Heart reactions pool: 💙 💝 💖 💕 💜 ❤️‍🔥 ☺️

Falls back to LLM-based kindness detection if keywords don't match.

Mood System

Available Moods

Each mood changes Miku's personality, response style, and nickname emoji. Defined in bot/moods/ (one .txt file per mood) and bot/globals.py.

Mood Emoji Description File
neutral (none) moods/neutral.txt
bubbly ✨ moods/bubbly.txt
sleepy 💤 moods/sleepy.txt
curious 🔍 moods/curious.txt
shy 🥺 moods/shy.txt
serious 😐 moods/serious.txt
excited 🎉 moods/excited.txt
silly 🤪 moods/silly.txt
melancholy 💙 moods/melancholy.txt
flirty 💕 moods/flirty.txt
romantic 💖 moods/romantic.txt
irritated 😤 moods/irritated.txt
angry 😠 moods/angry.txt
asleep 😴 moods/asleep.txt

Mood behavior:

  • DM moods rotate automatically on a schedule.
  • Server moods are per-server and can be set manually via the API or auto-detected from conversation tone.
  • Mood affects the system prompt, nickname emoji, and profile picture selection.
  • The asleep mood can only be reached from sleepy (prevents accidental sleep).

Evil Mode Moods

When Evil Mode is active, a separate mood set is used:

Evil Mood Emoji
aggressive 👿
cunning 🐍
sarcastic 😈
evil_neutral (none)

Mood Auto-Detection

After Miku responds in a server, the system analyzes her response to detect if a mood shift occurred naturally. Handled by detect_mood_shift() in bot/utils/moods.py. If detected, the server mood updates automatically and the bot nickname updates.

Personality Modes

Evil Mode

File: bot/utils/evil_mode.py

Evil Mode transforms Miku into "Evil Miku" — an uncensored, darker alter ego. When enabled:

  • Uses the EVIL_TEXT_MODEL (DarkIdol uncensored model) instead of the standard text model.
  • Loads evil-specific prompts from bot/evil_miku_prompt.txt, bot/evil_miku_lore.txt, bot/evil_miku_lyrics.txt.
  • Changes the bot's username and profile picture across all servers.
  • Changes role color to a dark theme.
  • Uses the evil mood set (aggressive, cunning, sarcastic, evil_neutral).
  • State persists across restarts via memory/evil_mode_state.json.

Bipolar Mode

File: bot/utils/bipolar_mode.py

When enabled, both Regular Miku and Evil Miku coexist. After Miku responds to a message, there's a chance (15%) the opposite persona "breaks through" and starts an argument. Arguments happen via Discord webhooks so both personas appear as different users.

Features:

  • Minimum 4 exchanges before an argument can end.
  • 2-5 second delay between messages for realism.
  • Scoreboard tracks wins (memory/bipolar_scoreboard.json).
  • Webhooks are created per-channel and cached.
  • Paused during voice sessions.
  • Arguments can be manually triggered via the API.

Persona Dialogue

File: bot/utils/persona_dialogue.py

After Miku sends a response in bipolar mode, the system checks if the opposite persona wants to "interject" and start a dialogue. This creates multi-turn conversations between the two Miku personas.

Voice Chat System

Voice Architecture

The voice system uses a dual-GPU setup:

  • AMD RX 6800 XT: Text model inference + RVC (voice conversion)
  • GTX 1660: Soprano TTS (text-to-speech)

STT (Speech-to-Text)

File: bot/utils/stt_client.py, bot/utils/voice_receiver.py

  • Uses a separate STT server container.
  • Listens to user audio via Discord voice receive.
  • Transcribes speech and sends it to the LLM for a response.
  • Can be enabled per-user with !miku listen.

TTS (Text-to-Speech)

File: bot/utils/voice_audio.py

  • Streams LLM output tokens directly to Soprano TTS.
  • Audio is played back through the Discord voice connection.
  • RVC converts the voice to sound like Miku.

Resource Locking

When a voice session is active, the following features are blocked:

  • ❌ Vision model (images/videos can't be analyzed)
  • ❌ Image generation (ComfyUI)
  • ❌ Bipolar mode arguments
  • ❌ Profile picture changes
  • ⏸️ Autonomous engine (paused)
  • ⏸️ Scheduled events (paused)
  • 📦 Other text channel messages (queued for later)

Resources are fully released when the session ends with !miku leave.

Autonomous Behavior System

Files: bot/utils/autonomous.py, bot/utils/autonomous_engine.py, bot/utils/autonomous_v1_legacy.py

Miku has an AI-driven autonomous system (V2) that decides when and how to interact without being prompted. The system uses context signals and mood profiles to make decisions.

Autonomous actions:

Action Description
general Say something spontaneous in the autonomous channel
engage_user Engage a random active user (based on activity, status, etc.)
share_tweet Share a Miku-related tweet
join_conversation Detect and join an ongoing conversation
change_profile_picture Autonomously change the bot's profile picture
reaction React to a recent message with an emoji

Context signals the engine considers:

  • Messages in the last 5 minutes / last hour
  • Unique active users
  • Conversation momentum
  • Users who recently joined / changed status / started activities
  • Time since last action / last interaction
  • Hour of day and whether it's a weekend
  • Current mood energy level

Scheduling: Each server has its own autonomous tick scheduler. Actions are rate-limited (minimum 30s between actions).

Memory System (Cheshire Cat)

Files: bot/utils/cat_client.py, cheshire-cat/ directory

Miku uses the Cheshire Cat AI framework for long-term memory:

  • Declarative memory: Learned facts about users and the world.
  • Episodic memory: Conversation snippets and experiences.
  • Memories are stored in vector databases (Qdrant).
  • When enabled, all responses are augmented with relevant memories.
  • Falls back to direct LLM queries if Cat is unavailable.
  • Memory consolidation can be triggered manually (like a "sleep" process).
  • Individual memories can be created, edited, and deleted via the API.

Toggle state: USE_CHESHIRE_CAT global (default: true).

Profile Picture System

File: bot/utils/profile_picture_manager.py, bot/utils/danbooru_client.py, bot/utils/pfp_context.py

  • Miku's profile picture can change based on mood.
  • Sources images from Danbooru (anime art database).
  • Extracts dominant colors for role color matching.
  • Face detection ensures the selected image has a face.
  • Saves a fallback image for restoration.
  • Can be triggered autonomously or manually via the API.
  • Custom images can be uploaded.

Language Modes

Miku supports switching between English and Japanese:

  • English mode (default): Uses the standard TEXT_MODEL.
  • Japanese mode: Uses JAPANESE_TEXT_MODEL (Llama 3.1 Swallow) for Japanese responses.
  • Persisted across restarts via config_runtime.yaml.

Figurine Notifier

File: bot/utils/figurine_notifier.py

DM-based subscription system for Miku figurine notifications:

  • Users can subscribe/unsubscribe to figurine alerts.
  • When new Miku figurines are posted (via tweet URLs), subscribers get DMs.
  • Individual or bulk DM sending supported.

Web UI API Endpoints

The bot runs a FastAPI server on port 3939 for the Web UI dashboard. All endpoints are defined in bot/api.py.

General Status

Method Endpoint Description
GET / Serve the Web UI dashboard
GET /status Bot status, DM mood, server count, per-server moods
GET /logs Last 100 lines of bot.log
GET /prompt Last full prompt sent to the LLM

Mood Management (DM)

Method Endpoint Description
GET /mood Get current DM mood and description
POST /mood Set DM mood ({ "mood": "bubbly" })
POST /mood/reset Reset DM mood to neutral
POST /mood/calm Calm DM mood to neutral
GET /moods/available List all available mood names

Mood Management (Per-Server)

Method Endpoint Description
GET /servers/{guild_id}/mood Get current mood for a server
POST /servers/{guild_id}/mood Set mood for a server
POST /servers/{guild_id}/mood/reset Reset server mood to neutral
GET /servers/{guild_id}/mood/state Get complete mood state for a server
POST /test/mood/{guild_id} Debug endpoint to test mood changes

Language

Method Endpoint Description
GET /language Get current language mode and model
POST /language/toggle Toggle between English and Japanese
POST /language/set Set language (?language=english or japanese)

Evil Mode API

Method Endpoint Description
GET /evil-mode Get evil mode status and current mood
POST /evil-mode/enable Enable evil mode
POST /evil-mode/disable Disable evil mode
POST /evil-mode/toggle Toggle evil mode
GET /evil-mode/mood Get current evil mood
POST /evil-mode/mood Set evil mood ({ "mood": "aggressive" })

Bipolar Mode API

Method Endpoint Description
GET /bipolar-mode Status, active arguments, webhooks count
POST /bipolar-mode/enable Enable bipolar mode
POST /bipolar-mode/disable Disable bipolar mode
POST /bipolar-mode/toggle Toggle bipolar mode
POST /bipolar-mode/trigger-argument Manually trigger an argument in a channel
POST /bipolar-mode/trigger-dialogue Force persona dialogue from a message
GET /bipolar-mode/scoreboard Miku vs Evil Miku win/loss record
GET /bipolar-mode/arguments Get all currently active arguments
POST /bipolar-mode/cleanup-webhooks Clean up all bipolar webhooks

GPU Selection

Method Endpoint Description
GET /gpu-status Current GPU selection (nvidia or amd)
POST /gpu-select Switch GPU ({ "gpu": "nvidia" } or "amd")

Autonomous Actions

Method Endpoint Description
POST /autonomous/general Trigger a general autonomous message (all servers or ?guild_id=)
POST /autonomous/engage Trigger user engagement (?guild_id=, ?user_id=, ?engagement_type=)
POST /autonomous/tweet Share a Miku tweet
POST /autonomous/custom Send custom prompt as autonomous message ({ "prompt": "..." })
POST /autonomous/reaction Trigger an emoji reaction to a recent message
POST /autonomous/join-conversation Detect and join an active conversation
GET /autonomous/stats V1 autonomous engine stats for all servers
POST /servers/{guild_id}/autonomous/general Trigger general message for one server
POST /servers/{guild_id}/autonomous/engage Trigger engagement for one server
POST /servers/{guild_id}/autonomous/custom Send custom prompt to one server
POST /servers/{guild_id}/autonomous/tweet Share tweet in one server

Profile Picture & Role Color

Method Endpoint Description
POST /profile-picture/change Change PFP (optional file upload, optional ?guild_id=)
GET /profile-picture/metadata Get current PFP metadata (source, tags, etc.)
POST /profile-picture/restore-fallback Restore the original saved PFP
POST /role-color/custom Set custom role color (form field hex_color)
POST /role-color/reset-fallback Reset role color to Miku teal (#86cecb)

Manual Messaging

Method Endpoint Description
POST /manual/send Send a message to a channel (supports files, replies)
POST /manual/send-webhook Send as Miku or Evil Miku via webhook (`persona=miku
POST /dm/{user_id}/custom Send a custom LLM-generated DM to a user
POST /dm/{user_id}/manual Send a manual DM message (supports files, replies)

Server Management

Method Endpoint Description
GET /servers List all configured servers
POST /servers Add a new server configuration
PUT /servers/{guild_id} Update server configuration
DELETE /servers/{guild_id} Remove a server
POST /servers/{guild_id}/bedtime-range Update bedtime reminder schedule
GET /servers/{guild_id}/memory Get server-specific memory
POST /servers/{guild_id}/memory Set server-specific memory
POST /servers/repair Repair corrupted server configuration

DM Logging & Management

Method Endpoint Description
GET /dms/users List all users who have DMed the bot
GET /dms/users/{user_id} Get conversation summary for a user
GET /dms/users/{user_id}/conversations Get recent conversations (?limit=50)
GET /dms/users/{user_id}/search Search conversations (?query=...)
GET /dms/users/{user_id}/export Export conversations (?format=json)
DELETE /dms/users/{user_id} Delete all DM logs for a user
GET /dms/blocked-users List all blocked users
POST /dms/users/{user_id}/block Block a user from DMs
POST /dms/users/{user_id}/unblock Unblock a user
POST /dms/users/{user_id}/conversations/{id}/delete Delete a specific message from Discord + logs
POST /dms/users/{user_id}/conversations/delete-all Delete all conversations (Discord + logs)
POST /dms/users/{user_id}/delete-completely Completely remove all user data

DM Interaction Analysis

Method Endpoint Description
POST /dms/analysis/run Manually trigger daily DM analysis
POST /dms/users/{user_id}/analyze Analyze a specific user's interactions
GET /dms/analysis/reports Get recent analysis reports (?limit=20)
GET /dms/analysis/reports/{user_id} Get reports for a specific user

Image Generation API

Method Endpoint Description
POST /image/generate Manually trigger image generation ({ "prompt": "..." })
GET /image/status Check ComfyUI availability
POST /image/test-detection Test natural language image request detection
GET /image/view/{filename} Serve a generated image file

Figurine DM Subscriptions

Method Endpoint Description
GET /figurines/subscribers List all figurine notification subscribers
POST /figurines/subscribers Add a subscriber (form field user_id)
DELETE /figurines/subscribers/{user_id} Remove a subscriber
POST /figurines/send_now Send figurine DMs to all subscribers
POST /figurines/send_to_user Send figurine DM to a specific user

Chat Interface

Method Endpoint Description
POST /chat/stream Stream a chat response via SSE (supports text and vision models, conversation history, mood selection)

Voice Call Management

Method Endpoint Description
POST /voice/call Initiate a voice call to a user (starts containers, joins channel, sends DM invite)
GET /voice/debug-mode Get voice debug mode status
POST /voice/debug-mode Set voice debug mode on/off

Memory (Cheshire Cat) API

Method Endpoint Description
GET /memory/status Cat connection status, circuit breaker state
POST /memory/toggle Enable/disable Cheshire Cat integration
GET /memory/stats Memory collection statistics (point counts)
GET /memory/facts Get all declarative memory facts
GET /memory/episodic Get all episodic memories
POST /memory/consolidate Trigger memory consolidation
POST /memory/delete Delete ALL memories (requires exact confirmation string)
DELETE /memory/point/{collection}/{point_id} Delete a single memory point
PUT /memory/point/{collection}/{point_id} Edit a memory point's content/metadata
POST /memory/create Create a new memory (declarative or episodic)

Configuration Management

Method Endpoint Description
GET /config Full config (static + runtime + state)
GET /config/static Static config from config.yaml
GET /config/runtime Runtime config (overrides)
POST /config/set Set a runtime config value
POST /config/reset Reset config to defaults
POST /config/validate Validate current configuration
GET /config/state Get current config state

Logging Configuration

Method Endpoint Description
GET /api/log/config Get current logging configuration
POST /api/log/config Update logging config for a component
GET /api/log/components List all logging components and stats
POST /api/log/reload Reload all loggers from config
POST /api/log/filters Update API request log filters
POST /api/log/reset Reset logging config to defaults
POST /api/log/global-level Set global log level
POST /api/log/timestamp-format Set timestamp format
GET /api/log/files/{component} Get last N lines from a component's log file

Message Reactions

Method Endpoint Description
POST /messages/react Add a reaction emoji to a specific message

Autonomous V2 Endpoints

Method Endpoint Description
GET /autonomous/v2/stats/{guild_id} V2 social stats for a server
GET /autonomous/v2/check/{guild_id} Manual V2 context check (debug)
GET /autonomous/v2/status V2 system status for all servers

Conversation Management

Method Endpoint Description
GET /conversation/{user_id} Get conversation history for a user
POST /conversation/reset Reset conversation history ({ "user_id": "..." })
POST /sleep Force Miku to sleep (legacy)
POST /wake Wake Miku up (legacy)
POST /bedtime Send bedtime reminder (?guild_id= or all servers)

Discord Event Handlers

These are non-command behaviors handled by Discord events in bot/bot.py:

Event Handler Description
on_ready bot.py ~L89 Initialize all systems, restore modes, start schedulers
on_message bot.py ~L160 Main message handler — routes commands, handles conversations
on_raw_reaction_add bot.py ~L716 Log DM reactions (user and bot)
on_raw_reaction_remove bot.py ~L756 Log DM reaction removals
on_presence_update bot.py ~L793 Track user presence for autonomous V2
on_member_join bot.py ~L799 Track member joins for autonomous V2
on_voice_state_update bot.py ~L803 Track voice channel joins/leaves, auto-listen for voice calls

Environment Variables

Key configuration from bot/globals.py and bot/config.py:

Variable Default Description
DISCORD_BOT_TOKEN — Discord bot token
LLAMA_URL http://llama-swap:8080 NVIDIA GPU llama-swap URL
LLAMA_AMD_URL http://llama-swap-amd:8080 AMD GPU llama-swap URL
TEXT_MODEL llama3.1 Default text model name
VISION_MODEL vision Vision model name (Qwen)
EVIL_TEXT_MODEL darkidol Uncensored model for evil mode
JAPANESE_TEXT_MODEL swallow Japanese text model
OWNER_USER_ID 209381657369772032 Bot owner's Discord ID (for reports)
CHESHIRE_CAT_URL http://cheshire-cat:80 Cheshire Cat memory server URL
USE_CHESHIRE_CAT true Enable/disable memory system
AUTONOMOUS_DEBUG false Verbose autonomous decision logging
VOICE_DEBUG_MODE false Show voice transcriptions in text channel
Reference in New Issue View Git Blame Copy Permalink