If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jagrosh/MusicBot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 14 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jagrosh/MusicBot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jagrosh/MusicBot.

What it runs against: a local clone of jagrosh/MusicBot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jagrosh/MusicBot | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 568 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jagrosh/MusicBot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jagrosh/MusicBot.git
#   cd MusicBot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jagrosh/MusicBot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jagrosh/MusicBot(\\.git)?\\b" \\
  && ok "origin remote is jagrosh/MusicBot" \\
  || miss "origin remote is not jagrosh/MusicBot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main/java/com/jagrosh/jmusicbot/JMusicBot.java" \\
  && ok "src/main/java/com/jagrosh/jmusicbot/JMusicBot.java" \\
  || miss "missing critical file: src/main/java/com/jagrosh/jmusicbot/JMusicBot.java"
test -f "src/main/java/com/jagrosh/jmusicbot/Bot.java" \\
  && ok "src/main/java/com/jagrosh/jmusicbot/Bot.java" \\
  || miss "missing critical file: src/main/java/com/jagrosh/jmusicbot/Bot.java"
test -f "src/main/java/com/jagrosh/jmusicbot/audio/PlayerManager.java" \\
  && ok "src/main/java/com/jagrosh/jmusicbot/audio/PlayerManager.java" \\
  || miss "missing critical file: src/main/java/com/jagrosh/jmusicbot/audio/PlayerManager.java"
test -f "src/main/java/com/jagrosh/jmusicbot/BotConfig.java" \\
  && ok "src/main/java/com/jagrosh/jmusicbot/BotConfig.java" \\
  || miss "missing critical file: src/main/java/com/jagrosh/jmusicbot/BotConfig.java"
test -f "src/main/java/com/jagrosh/jmusicbot/audio/AudioHandler.java" \\
  && ok "src/main/java/com/jagrosh/jmusicbot/audio/AudioHandler.java" \\
  || miss "missing critical file: src/main/java/com/jagrosh/jmusicbot/audio/AudioHandler.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 568 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~538d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jagrosh/MusicBot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

JMusicBot is a self-hosted Discord music bot built on JDA (Java Discord API) and lavaplayer that streams music from YouTube, SoundCloud, Bandcamp, Twitch, and local files into Discord voice channels. It requires only a Discord bot token and Java runtime—no external API keys—and handles playback, queuing, and per-guild DJ role permissions out of the box. Monolithic Java structure: src/main/java/com/jagrosh/jmusicbot/ is the root. Core entry points are JMusicBot.java (main) and Bot.java (initialization). Audio handling lives in audio/ (AudioHandler, PlayerManager, QueuedTrack). Commands are organized hierarchically: commands/AdminCommand.java, commands/DJCommand.java as base classes, with concrete implementations in commands/admin/ and commands/dj/ subdirectories. Configuration is externalized to BotConfig.java.

Discord server administrators and power users who want a music bot they control and host themselves, without relying on third-party services. Developers contributing to the project are typically Java/Discord API enthusiasts interested in bot command architecture and audio streaming patterns.

Production-ready and actively maintained. The project has 6000+ GitHub stars, CircleCI + GitHub Actions CI/CD configured (see .circleci/config.yml and .github/workflows/build-and-test.yml), and structured GitHub issue templates for bug reports and feature requests. Regular releases and discussions indicate steady community engagement.

Low technical risk for users (it's a standalone JAR with no external service dependency), but the codebase is single-author-maintained by jagrosh. Dependency chain includes JDA 4.4.1, lavaplayer 2.2.1, and jda-utilities 3.0.5 from multiple custom Maven repositories (dv8tion, jitpack, duncte123, arbjerg)—any breaking changes in those upstreams could require swift patches. No visible test suite in the file list is a minor concern for long-term refactoring safety.

Active development with GitHub Actions workflows for build-and-test and automated releases. Recent focus on stability and CI/CD robustness (both CircleCI and GitHub Actions configured). The presence of FUNDING.yml and structured PR/issue templates suggests ongoing community management.

git clone https://github.com/jagrosh/MusicBot.git
cd MusicBot
mvn clean package
java -jar target/JMusicBot-Snapshot.jar

Alternatively, use the provided shell script: bash scripts/run_jmusicbot.sh (after Maven build).

Daily commands:

mvn clean compile exec:java -Dexec.mainClass="com.jagrosh.jmusicbot.JMusicBot"

Or build a JAR and run: java -jar target/JMusicBot-Snapshot.jar. Requires a Discord bot token in configuration (set via BotConfig.java or environment variables).

• src/main/java/com/jagrosh/jmusicbot/JMusicBot.java — Main entry point for the bot; initializes the JDA client and core bot components.
• src/main/java/com/jagrosh/jmusicbot/Bot.java — Core bot orchestrator that manages command registration, event listeners, and bot lifecycle.
• src/main/java/com/jagrosh/jmusicbot/audio/PlayerManager.java — Manages audio playback and track loading via Lavaplayer; essential for music functionality.
• src/main/java/com/jagrosh/jmusicbot/BotConfig.java — Loads and parses configuration from files; drives all bot behavior and settings.
• src/main/java/com/jagrosh/jmusicbot/audio/AudioHandler.java — Handles audio events and queue management for individual Discord voice channels.
• src/main/java/com/jagrosh/jmusicbot/commands/music/PlayCmd.java — Primary user-facing command for queueing tracks; demonstrates command architecture pattern.
• pom.xml — Maven build configuration; declares all dependencies (JDA, Lavaplayer, LavaPlayer sources).

Add a new Music Command

1. Create a new class extending MusicCommand in src/main/java/com/jagrosh/jmusicbot/commands/music/ (src/main/java/com/jagrosh/jmusicbot/commands/music/YourNewCmd.java)
2. Implement getName(), getHelp(), and execute(CommandEvent) methods; access AudioHandler via event.getGuild() (src/main/java/com/jagrosh/jmusicbot/commands/music/YourNewCmd.java)
3. Register the command in Bot.java by adding it to the CommandClientBuilder (src/main/java/com/jagrosh/jmusicbot/Bot.java)
4. If your command needs persistent settings, add fields to Settings.java and SettingsManager.java (src/main/java/com/jagrosh/jmusicbot/settings/Settings.java)

Bot token setup: No token is committed; must be provided via config.txt in the working directory or environment variable (check BotConfig.java for exact config file format). Java version: Requires Java 8+; no explicit version constraint visible in pom.xml, but JDA 4.4.1 is tested against Java 11+. Lavaplayer native dependencies: Audio playback requires ffmpeg or avconv on the system PATH—the bot will fail silently if unavailable. Guild-specific permissions: Commands check for DJ role or admin permissions per guild; local testing with a single bot token requires manual role setup in Discord. No in-process persistence: Settings are written to files (config.txt, guilds/), not a database—file I/O errors will silently drop changes.

• LavaPlayer audio source abstraction — Understanding how lavaplayer loads tracks from different sources (YouTube, local files, HTTP streams) is essential to extending the bot's audio capabilities or debugging playback failures
• JDA event listener pattern — The bot relies on JDA's event-driven model (ListenerAdapter, EventListener); understanding how Listener.java reacts to Discord events is crucial for modifying bot behavior
• Discord voice channel audio streaming (Opus codec) — JMusicBot sends audio to voice channels via Discord's Opus-encoded RTP streams; understanding this protocol is necessary for debugging audio quality or latency issues
• Guild-scoped command permissions (role-based access control) — The bot enforces per-guild DJ roles and admin roles via checks in command base classes (DJCommand.java, AdminCommand.java); this pattern is central to multi-guild security
• Audio queue and track scheduling — Core bot function relies on AudioHandler managing a queue of QueuedTrack objects and scheduling playback; understanding the queue state machine prevents sync bugs
• Maven multi-repository artifact resolution — pom.xml pulls dependencies from 5 custom Maven repositories (dv8tion, jitpack, duncte123, arbjerg); understanding how Maven resolves conflicts and snapshots is necessary for dependency management and CI stability
• Discord message reaction menus — Bot uses jda-utilities' Menu and reaction-based pagination (likely via PaginatedBuilder or similar) for displaying playlists and results; understanding this pattern is needed to add new interactive features

• discord-jda/JDA — Official Java Discord API library that JMusicBot depends on; essential for understanding how Discord events and entities work
• lavalink-devs/Lavalink — Standalone audio server alternative to embedded lavaplayer; users seeking distributed music bot architecture often evaluate Lavalink
• sedmelluq/lavaplayer — Audio playback engine JMusicBot is built on; source for track loading and format support
• jagrosh/JDA-Utilities — Companion utility library (included in pom.xml) providing command framework and menu builders used throughout JMusicBot
• Frederikam/FredBoat — Alternative Java Discord music bot with Lavalink integration; reference for competing architecture and feature set

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for audio handlers (AudioHandler, AloneInVoiceHandler, NowplayingHandler)

The audio subsystem is critical to the bot's functionality but appears to have no test coverage. The src/main/java/com/jagrosh/jmusicbot/audio/ directory contains core components like AudioHandler.java, PlayerManager.java, and QueuedTrack.java that manage playback state, queue management, and track metadata. Adding unit tests for these classes would catch regressions in audio behavior, queue operations, and alone-in-voice timeout handling.

• [ ] Create src/test/java/com/jagrosh/jmusicbot/audio/ directory structure
• [ ] Add unit tests for AudioHandler.java covering queue operations, volume changes, and playback state
• [ ] Add unit tests for AloneInVoiceHandler.java covering timeout logic and channel cleanup
• [ ] Add unit tests for QueuedTrack.java and RequestMetadata.java covering serialization and track metadata
• [ ] Integrate tests into build-and-test.yml GitHub Action workflow
• [ ] Ensure tests achieve >70% code coverage for the audio module

Add integration tests for command execution (MusicCommand, DJCommand, AdminCommand)

The commands directory has extensive command implementations (PlayCmd, SkipCmd, PauseCmd, etc.) but no visible test coverage. Commands inherit from MusicCommand, DJCommand, AdminCommand, and OwnerCommand base classes. Creating integration tests would validate command parsing, permission checking, and expected behavior without needing a live Discord bot.

• [ ] Create src/test/java/com/jagrosh/jmusicbot/commands/ directory with test utilities for mocking JDA events
• [ ] Add tests for MusicCommand.java base class covering permission validation and audio handler access
• [ ] Add tests for at least 3 representative commands: PlayCmd.java, SkipCmd.java, and PauseCmd.java
• [ ] Add tests for DJCommand.java and AdminCommand.java permission enforcement
• [ ] Use JUnit 5 and Mockito to mock Discord/JDA objects
• [ ] Update pom.xml with junit-jupiter and mockito dependencies if missing

Add GitHub Actions workflow for code quality checks (SpotBugs, Checkstyle, SonarQube analysis)

The repo has build-and-test.yml and make-release.yml workflows but lacks static analysis. With 25+ command classes and complex audio handling, a code quality pipeline would catch potential bugs (NullPointerExceptions, resource leaks), enforce style consistency, and identify technical debt. This is especially valuable for a widely-forked open source bot.

• [ ] Add SpotBugs Maven plugin to pom.xml with configuration to fail on high-priority bugs
• [ ] Add Checkstyle Maven plugin to pom.xml using Google Java Style Guide ruleset
• [ ] Create .github/workflows/code-quality.yml that runs SpotBugs and Checkstyle on PRs
• [ ] Configure SonarQube analysis step (using Community Edition) in the workflow
• [ ] Add build badges to README.md for code quality status
• [ ] Document any existing code style conventions in CONTRIBUTING.md or update CODE_OF_CONDUCT.md

• Add unit tests for QueuedTrack.java and RequestMetadata.java under src/test/ (currently no test directory exists); these are core data models with no test coverage visible.
• Document the exact format of config.txt and per-guild settings files in a new CONFIG.md file at repo root—currently only mentioned in BotConfig.java code comments, not user-facing docs.
• Add a NowplayingHandler test or example output in README under a new 'Now Playing' section—the handler exists but is never demonstrated to users.

• High · Outdated JDA Dependency — pom.xml - JDA dependency. JDA version 4.4.1_353 is used. This version may contain known security vulnerabilities. JDA is a critical dependency for Discord API interactions and should be kept current to receive security patches. Fix: Update JDA to the latest stable version (5.x or newer) and review release notes for security fixes.
• High · Potential Code Execution via EvalCmd — src/main/java/com/jagrosh/jmusicbot/commands/owner/EvalCmd.java. The file 'EvalCmd.java' in owner commands suggests arbitrary code evaluation capability. If not properly restricted to owner-only users, this could allow remote code execution attacks. Fix: Ensure EvalCmd has strict owner-only access controls. Validate that OwnerCommand.java properly authenticates owner status before execution. Consider removing eval functionality if not essential.
• Medium · Insecure Repository Configuration — pom.xml - repository definitions. The pom.xml includes multiple external repositories (jitpack.io, m2.duncte123.dev) that may not have the same security standards as Maven Central. JitPack in particular builds from arbitrary GitHub repositories. Fix: Prioritize Maven Central Repository. If external repos are necessary, implement dependency verification and consider using repository mirrors with access controls. Enable checksum validation.
• Medium · Hardcoded Configuration Values — src/main/java/com/jagrosh/jmusicbot/BotConfig.java. BotConfig.java likely contains configuration values. If credentials, tokens, or API keys are hardcoded here, they could be exposed in version control or compiled artifacts. Fix: Externalize all sensitive configuration (API keys, tokens, credentials) to environment variables or secure configuration files not tracked in version control. Use .gitignore for config files.
• Medium · Missing Dependency Version Pinning — pom.xml - incomplete dependency definitions. The pom.xml appears incomplete (lavaplayer version is cut off). Unpinned transitive dependencies can lead to supply chain attacks or unexpected behavior from dependency updates. Fix: Complete and explicitly pin all dependency versions. Use Maven dependency management section to centralize version control. Run 'mvn dependency:tree' to verify transitive dependencies.
• Medium · Audio File Handling Security — src/main/java/com/jagrosh/jmusicbot/audio/ and src/main/java/com/jagrosh/jmusicbot/playlist/PlaylistLoader.java. Files in src/main/java/com/jagrosh/jmusicbot/audio/ handle music streams and playback. Improper URL validation in PlayCmd.java or playlist loading could lead to SSRF attacks or malicious content injection. Fix: Validate and sanitize all user-provided URLs before loading. Implement whitelist of allowed domains if possible. Validate playlist file contents before parsing.
• Medium · Potential Information Disclosure in Lyrics Command — src/main/java/com/jagrosh/jmusicbot/commands/music/LyricsCmd.java. LyricsCmd.java queries external APIs for lyrics. Error messages or debugging information from API responses could leak sensitive information about the bot's architecture or users. Fix: Sanitize API error responses before displaying to users. Log detailed errors server-side only. Implement rate limiting on external API calls.
• Low · Debug Command Exposure — src/main/java/com/jagrosh/jmusicbot/commands/owner/DebugCmd.java. DebugCmd.java exists in owner commands. Debug functionality could leak sensitive information if not properly restricted. Fix: Ensure debug commands are owner-only and remove detailed system information from output. Consider disabling debug endpoints in production builds.
• Low · Missing HTTPS Enforcement — .circleci/config.yml and .github/workflows/. Repository URLs in pom.xml use HTTPS, but CircleCI config and GitHub Actions workflows should enforce HTTPS for all external communication. Fix: Verify all CI/CD workflows use

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.