{"id":48590372,"url":"https://github.com/thecodeversehub/miku","last_synced_at":"2026-04-08T19:03:13.342Z","repository":{"id":342268816,"uuid":"1173434518","full_name":"TheCodeVerseHub/Miku","owner":"TheCodeVerseHub","description":"Miku is a cute, general-purpose Discord bot that provides leveling, reaction roles and useful server utilities. Built as an open-source project by The Codeverse Hub to help communities manage and grow their Discord servers easily.","archived":false,"fork":false,"pushed_at":"2026-04-05T11:19:16.000Z","size":395,"stargazers_count":3,"open_issues_count":9,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T12:21:21.086Z","etag":null,"topics":["bot","contribution","contributions-welcome","discord","discord-api","discord-bot","discord-py","open-source","oss"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheCodeVerseHub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T11:09:21.000Z","updated_at":"2026-04-05T11:19:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TheCodeVerseHub/Miku","commit_stats":null,"previous_names":["thecodeversehub/miku"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheCodeVerseHub/Miku","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheCodeVerseHub%2FMiku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheCodeVerseHub%2FMiku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheCodeVerseHub%2FMiku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheCodeVerseHub%2FMiku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheCodeVerseHub","download_url":"https://codeload.github.com/TheCodeVerseHub/Miku/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheCodeVerseHub%2FMiku/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31569400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","contribution","contributions-welcome","discord","discord-api","discord-bot","discord-py","open-source","oss"],"created_at":"2026-04-08T19:02:48.627Z","updated_at":"2026-04-08T19:03:13.333Z","avatar_url":"https://github.com/TheCodeVerseHub.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Miku - Discord Leveling Bot\n\nA feature-rich Discord leveling bot inspired by Arcane, with support for both **slash commands** and **prefix commands** (prefix: `\u0026`).\n\n## Features\n\n- **XP \u0026 Leveling System** - Users gain 15-25 XP per message (60-second cooldown)\n- **Rank Cards** - Beautiful embeds showing user rank, level, and progress\n- **Leaderboards** - View top members by XP with pagination\n- **Hybrid Commands** - Works with both `/` slash commands and `\u0026` prefix\n- **PostgreSQL Database** - Persistent data storage via `asyncpg`\n- **Rich Embeds** - Clean, visually appealing messages\n- **Admin Tools** - Manage user levels and XP\n- **GitHub Integration** - Look up repos/users and search GitHub\n- **Utility / Fun / Info Commands** - General helpful commands and light games (no moderation)\n\n## Commands\n\n### Leveling Commands\n\n| Command | Slash | Prefix | Description |\n|---------|-------|--------|-------------|\n| **rank** | `/rank [user]` | `\u0026rank [user]` | Check your or another user's rank and level |\n| **level** | `/level [user]` | `\u0026level [user]` | Alias for rank command |\n| **leaderboard** | `/leaderboard [page]` | `\u0026leaderboard [page]` | View the server leaderboard (top 50) |\n| **lb** | `/lb [page]` | `\u0026lb [page]` | Alias for leaderboard |\n| **xp** | `/xp [user]` | `\u0026xp [user]` | Check detailed XP information |\n\n### Utility Commands\n\n| Command | Slash | Prefix | Description |\n|---------|-------|--------|-------------|\n| **ping** | `/ping` | `\u0026ping` | Check if the bot is responsive and view latency |\n| **uptime** | `/uptime` | `\u0026uptime` | Show how long the bot has been online |\n| **about** | `/about` | `\u0026about` | Bot information and basic stats |\n| **invite** | `/invite` | `\u0026invite` | Get a bot invite link |\n| **avatar** | `/avatar [user]` | `\u0026avatar [user]` | Show a user's avatar |\n| **userinfo** | `/userinfo [user]` | `\u0026userinfo [user]` | Show information about a server member |\n| **serverinfo** | `/serverinfo` | `\u0026serverinfo` | Show information about the current server |\n\n### Fun Commands\n\n| Command | Slash | Prefix | Description |\n|---------|-------|--------|-------------|\n| **8ball** | `/8ball \u003cquestion\u003e` | `\u00268ball \u003cquestion\u003e` | Ask the magic 8-ball |\n| **coinflip** | `/coinflip` | `\u0026coinflip` | Flip a coin |\n| **roll** | `/roll [sides]` | `\u0026roll [sides]` | Roll a dice (default d6) |\n| **choose** | `/choose \u003ca, b, c\u003e` | `\u0026choose \u003ca, b, c\u003e` | Choose one option from a comma-separated list |\n| **rps** | `/rps \u003cchoice\u003e` | `\u0026rps \u003cchoice\u003e` | Play rock-paper-scissors |\n\n### Info Commands\n\n| Command | Slash | Prefix | Description |\n|---------|-------|--------|-------------|\n| **membercount** | `/membercount` | `\u0026membercount` | Show the server member count |\n| **roleinfo** | `/roleinfo \u003crole\u003e` | `\u0026roleinfo \u003crole\u003e` | Show information about a role |\n| **channelinfo** | `/channelinfo [channel]` | `\u0026channelinfo [channel]` | Show information about a channel |\n\n### GitHub Commands\n\nAll GitHub commands are under the `github` / `gh` group:\n\n| Command | Slash | Prefix | Description |\n|---------|-------|--------|-------------|\n| **github repo** | `/github repo \u003cowner/repo\u003e` | `\u0026github repo \u003cowner/repo\u003e` | View repository information |\n| **github user** | `/github user \u003cusername\u003e` | `\u0026github user \u003cusername\u003e` | View a user/organisation profile |\n| **github search-repos** | `/github search-repos \u003cquery\u003e` | `\u0026github search-repos \u003cquery\u003e` | Search repositories |\n| **github search-users** | `/github search-users \u003cquery\u003e` | `\u0026github search-users \u003cquery\u003e` | Search users |\n\n### Admin Commands (Requires Administrator Permission)\n\n| Command | Slash | Prefix | Description |\n|---------|-------|--------|-------------|\n| **setlevel** | `/setlevel \u003cuser\u003e \u003clevel\u003e` | `\u0026setlevel \u003cuser\u003e \u003clevel\u003e` | Set a user's level |\n| **addxp** | `/addxp \u003cuser\u003e \u003camount\u003e` | `\u0026addxp \u003cuser\u003e \u003camount\u003e` | Add XP to a user |\n| **resetlevel** | `/resetlevel \u003cuser\u003e` | `\u0026resetlevel \u003cuser\u003e` | Reset a user's level data |\n| **resetalllevels** | `/resetalllevels CONFIRM` | `\u0026resetalllevels CONFIRM` | Reset all server levels (requires CONFIRM) |\n| **setlevelchannel** | `/setlevelchannel \u003cchannel\u003e` | `\u0026setlevelchannel #channel` | Set channel for level-up announcements |\n| **addrole** | `/addrole \u003clevel\u003e \u003crole\u003e` | `\u0026addrole \u003clevel\u003e @role` | Add role reward for a level |\n| **removerole** | `/removerole \u003clevel\u003e` | `\u0026removerole \u003clevel\u003e` | Remove role reward for a level |\n| **rolerewards** | `/rolerewards` | `\u0026rolerewards` | List all configured role rewards |\n\n## Setup\n\n### Prerequisites\n\n- Python 3.14+\n- Discord Bot Token\n- A PostgreSQL database URL (`DATABASE_URL`)\n- Required intents: Message Content, Server Members, Guilds\n\n### Installation\n\n1. **Clone the repository**\n```bash\ncd \"Miku\"\n```\n\n2. **Install dependencies**\n```bash\npip install -e .\n# or\nuv pip install -e .\n```\n\n3. **Configure environment**\nCreate a `.env` file or export the environment variable:\n```bash\nexport DISCORD_BOT_TOKEN='your_bot_token_here'\nexport DATABASE_URL='postgresql+asyncpg://user:password@host:5432/database'\n```\n\n4. **Run the bot**\n```bash\npython main.py\n```\n\n## Bot Setup on Discord Developer Portal\n\n1. Go to [Discord Developer Portal](https://discord.com/developers/applications)\n2. Create a new application or select your existing one\n3. Go to the **Bot** section\n4. Enable these **Privileged Gateway Intents**:\n   - Message Content Intent\n   - Server Members Intent\n   - Presence Intent (optional)\n5. Copy your bot token and set it as `DISCORD_BOT_TOKEN`\n6. Go to **OAuth2 \u003e URL Generator**\n7. Select scopes: `bot` and `applications.commands`\n8. Select permissions: \n   - Send Messages\n   - Embed Links\n   - Read Message History\n   - Use Slash Commands\n9. Use the generated URL to invite your bot\n\n## Leveling Formula\n\nThe bot uses a formula similar to Arcane/MEE6:\n\n```\nXP Required = 5 × (level²) + (50 × level) + 100\n```\n\n- **XP per message**: 15-25 (random)\n- **Cooldown**: 60 seconds between XP gains\n- **Level calculation**: Based on total accumulated XP\n\n### Example XP Requirements\n\n| Level | Total XP Needed |\n|-------|----------------|\n| 1 | 155 |\n| 5 | 1,000 |\n| 10 | 3,850 |\n| 20 | 14,600 |\n| 50 | 89,250 |\n\n## Project Structure\n\n```\nmain.py                 # Entrypoint (adds src/ to path and runs the bot)\n├── pyproject.toml       # Dependencies\n├── requirements.txt     # Python dependencies (optional)\n├── README.md            # Documentation\n└── src/\n   ├── bot.py            # Bot setup, DB init, cog loading\n   ├── cogs/\n   │   ├── leveling.py    # XP/levels/leaderboards\n   │   ├── help.py        # Interactive help menu\n   │   ├── github.py      # GitHub lookup/search\n   │   ├── utilities.py   # Utility commands\n   │   ├── fun.py         # Fun commands\n   │   └── info.py        # Info commands\n   └── utils/\n      ├── database.py     # PostgreSQL (asyncpg) DB layer\n      ├── github_client.py # GitHub API client\n      └── rank_card.py     # Rank card generator\n```\n\n## Features Breakdown\n\n### XP Gain System\n- Automatic XP on every message (excluding bots and DMs)\n- 60-second cooldown per user per guild\n- Random XP gain (15-25) to prevent farming\n- Level-up notifications with embeds\n\n### Rank Card\nShows:\n- User's rank in the server\n- Current level\n- Total messages sent\n- Progress bar to next level\n- Total XP earned\n\n### Leaderboard\n- Shows top 50 members\n- Paginated display (10 per page)\n- Medal emojis for top 3 ()\n- Displays level, XP, and message count\n\n### Database\n- Async PostgreSQL operations (asyncpg)\n- Tracks: user_id, guild_id, xp, level, messages, last_message_time\n- Auto-creates tables on first run\n- Data persists across restarts\n\n## Customization\n\n### Change XP Gain Range\nEdit in `src/cogs/leveling.py`:\n```python\nxp_gain = random.randint(15, 25)  # Change these values\n```\n\n### Change Cooldown Time\nEdit in `src/cogs/leveling.py`:\n```python\nself.cooldown_time = 60  # seconds\n```\n\n### Change Command Prefix\nEdit in `src/bot.py`:\n```python\ncommand_prefix='\u0026'  # Change to your preferred prefix\n```\n\n### Modify Level Formula\nEdit the `calculate_level` and `calculate_xp_for_level` methods in `src/cogs/leveling.py`\n\n## Troubleshooting\n\n### Bot doesn't respond to commands\n- Make sure Message Content intent is enabled\n- Check that the bot has proper permissions in the server\n- Verify the bot token is correct\n\n### Slash commands not showing\n- Wait up to 1 hour for global commands to sync\n- Try kicking and re-inviting the bot\n- Check bot has `applications.commands` scope\n\n### Database errors\n- Verify `DATABASE_URL` points to a reachable PostgreSQL instance\n- Confirm the database user can create tables (first run)\n\n## License\n\nThis project is open source and available for personal and educational use.\n\n## Contributing\n\nFeel free to fork, modify, and improve this bot! Contributions are welcome.\n\n## Tips\n\n- The bot works in multiple servers simultaneously\n- Each server has its own leaderboard and levels\n- Levels don't transfer between servers\n- Admin commands require Discord administrator permission\n- Level-up messages auto-delete after 10 seconds to reduce spam\n\n---\n\nMade with using discord.py\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodeversehub%2Fmiku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthecodeversehub%2Fmiku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodeversehub%2Fmiku/lists"}