GO — Healthy across all four use cases

• Last commit today
• 13 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Rmpc is a terminal-based Music Player Daemon (MPD) client written in Rust that displays album art via Kitty, Sixel, Iterm2, or ueberzuggpp protocols. It solves the problem of controlling MPD music playback with a modern, configurable TUI (similar to ncmpcpp and ranger) while adding features like synchronized lyrics, YouTube music integration, Cava visualizer support, and Lua scripting hooks. Cargo workspace with 4 members: rmpc/ (main TUI client, ~2M lines), rmpc-mpd/ (MPD protocol client library), rmpc-shared/ (shared types/config), and rmpcd/ (script daemon with Lua 5.5 via mlua). Core UI built on ratatui, state management uses crossterm for terminal control, config/theme in RON format (assets/example_config.ron, assets/example_theme.ron). Architecture separates MPD protocol handling from rendering.

Linux/Unix power users and music enthusiasts who run MPD servers and want a vim-keybindings-first, highly customizable terminal client with album art display. Contributors are Rust developers interested in TUI applications, MPD protocol implementation, and terminal image protocol handling.

Actively maintained and production-ready for daily use. The project has CI/CD workflows (ci.yml, release.yml, docs_deploy.yml), detailed CHANGELOG.md tracking, Nix packaging support, and presence on Repology indicating multi-distro adoption. The maintainer acknowledges rare breaking changes but emphasizes stability; this is not experimental but still evolving.

Moderate risk: The project is single-maintainer (mierak) with a monorepo spanning 4 workspace members requiring coordination. Heavy dependency graph (ratatui, mlua, zbus, tokio, image processing libraries) introduces supply-chain surface area. The Rust version constraint (1.88.0+) and MSRV tracking suggest active maintenance but could lag behind stable releases. Breaking changes are explicitly documented but possible, so pin versions in production.

No specific PR/milestone data in the file list, but the presence of GitHub Workflows (ci.yml with likely Rust testing, docs_deploy.yml suggesting website updates, release.yml for automation) and FUNDING.yml indicate active engagement. CHANGELOG.md suggests regular version bumps. Check .github/workflows/ci.yml to see current test matrix and .github/ISSUE_TEMPLATE/ for active issue categories (bug.yml, feature.yml).

git clone https://github.com/mierak/rmpc
cd rmpc
cargo build --release
./target/release/rmpc

Requires Rust 1.88.0+, MPD daemon running (typically localhost:6600), and a terminal supporting one of: Kitty, Sixel, Iterm2 protocols, or ueberzuggpp for album art.

Daily commands:

cargo build --release
./target/release/rmpc

For development with logging: RUST_LOG=debug cargo run. Requires MPD running; configure server address in ~/.config/rmpc/config.ron (see assets/example_config.ron for format). Optional: run rmpcd daemon for Lua scripting (Cargo.toml shows rmpcd member).

• rmpc/src/core/client.rs — Core MPD client abstraction that all UI components depend on; handles async communication with Music Player Daemon and state management.
• rmpc/src/config/mod.rs — Configuration system that loads and validates user settings from RON files; understanding this is essential for extending rmpc's configurability.
• rmpc-mpd/src/mpd_client.rs — Raw MPD protocol client implementation; critical abstraction layer between rmpc and the MPD daemon that all commands route through.
• rmpc/src/config/keys/actions.rs — Action definitions that bind keybindings to client commands; necessary for understanding how user input flows through the application.
• rmpc/Cargo.toml — Workspace and dependency manifest; critical for understanding the tech stack and build dependencies across all crates.
• rmpc-shared/src/lib.rs — Shared utilities and types used across rmpc, rmpc-mpd, and rmpcd; contains foundational abstractions for paths, environment, and version management.
• rmpc/src/config/theme/mod.rs — Theme configuration system for TUI rendering; essential for understanding how colors, styles, and UI elements are customized.

Add a new MPD command

1. Create a new command module in rmpc-mpd/src/commands/ that implements the MPD protocol command (e.g., create rmpc-mpd/src/commands/my_command.rs) (rmpc-mpd/src/commands/my_command.rs)
2. Export the command module in rmpc-mpd/src/commands/mod.rs (rmpc-mpd/src/commands/mod.rs)
3. Add a method to rmpc-mpd/src/client.rs that calls your command via self.exec() or self.exec_list() (rmpc-mpd/src/client.rs)
4. Expose the new method in rmpc/src/core/client.rs as an async wrapper that integrates with the application state (rmpc/src/core/client.rs)

Add a new keybinding and action

1. Add the new action variant to the Action enum in rmpc/src/config/keys/actions.rs with derive Deserialize (rmpc/src/config/keys/actions.rs)
2. Implement the handler for the action in rmpc/src/config/keys/actions.rs using the impl Action block (rmpc/src/config/keys/actions.rs)
3. Define the keymap binding in the config by adding a serde-compatible entry to the keys configuration structure (rmpc/src/config/keys/mod.rs)
4. The keybinding is automatically loaded from user config files (RON format) at runtime via rmpc/src/config/mod.rs

Add a new configuration option

1. Add the new config field to the appropriate config struct (e.g., AlbumArtConfig, CavaConfig, or ThemeConfig) with Deserialize derive (rmpc/src/config/mod.rs)
2. Provide default values in rmpc/src/config/defaults.rs (rmpc/src/config/defaults.rs)
3. Use the config value in the application logic, e.g., in rmpc/src/core/client.rs or UI rendering code (rmpc/src/core/client.rs)
4. Document the new option in assets/example_config.ron as a commented example (assets/example_config.ron)

Add a new color theme property

1. Create a new configuration struct in rmpc/src/config/theme/ (e.g., rmpc/src/config/theme/my_component.rs) with Deserialize (rmpc/src/config/theme/my_component.rs)
2. Include the new struct in rmpc/src/config/theme/mod.rs and add it to the Theme struct (rmpc/src/config/theme/mod.rs)
3. Apply the theme colors during TUI rendering by reading from the config in rmpc/src/core/client.rs or relevant UI component code (rmpc/src/core/client.rs)
4. Add example colors and styles to assets/example_theme.ron (assets/example_theme.ron)

• Rust + Tokio (async runtime) — Enables efficient concurrent handling of MPD socket communication, TUI event loops, and idle subscriptions without heavy threading
• Ratatui (TUI framework) — Provides cross-platform terminal UI rendering with immediate-mode drawing model, suitable for a music player interface
• MPD Protocol (plain TCP + text commands) — Native interface to Music Player Daemon; enables direct control without middleware, low overhead
• RON configuration format — Human-friendly, Rust-native serialization that supports comments and complex nested structures for user configuration
• Serde + custom deserializers — Flexible configuration parsing with strong type safety and validation at deserialization time

• Single-crate async event loop vs. multi-threaded architecture

  • Why: Tokio-based async is lighter and simpler for I/O-bound operations (socket reads, user input)
  • Consequence: CPU-bound operations (image rendering, lyrics parsing) may block the UI; mitigated by spawning blocking tasks

• User configuration via RON files instead of CLI-only or TOML

  • Why: undefined
  • Consequence: undefined

1. MPD connectivity: Rmpc expects MPD to be running on localhost:6600 by default; if tests fail, check your MPD instance. 2. Terminal protocol negotiation: Album art requires explicit terminal support (Kitty, Sixel, Iterm2) or ueberzuggpp wrapper—no fallback to ASCII art in this codebase, so testing on unsupported terminals will silently disable that feature. 3. RON config syntax: Configuration uses RON (Rusty Object Notation), not TOML or YAML; typos won't be caught until runtime. 4. Lua feature gating: Scripting via mlua requires the 'lua55' feature—check Cargo.toml for feature flags. 5. Crossterm termios usage: Low-level terminal control via rustix::termios; running under tmux or SSH may expose platform-specific quirks.

• MPD Protocol (Music Player Daemon) — Rmpc is entirely built around the MPD text protocol; you must understand commands (status, list, idle), response parsing, and the command/status cycle to work on rmpc-mpd or fix sync issues
• Terminal Image Protocols (Kitty, Sixel, Iterm2) — Album art rendering is a core feature differentiating rmpc from competitors; understanding how these protocols encode and display images in terminal frames is needed to debug or extend image support
• Ratatui TUI Framework — The entire UI (widgets, layout, event handling, rendering) is built on Ratatui; contributors working on screens, keybinds, or visual bugs must know Ratatui's backend trait, frame structure, and widget composition
• Tokio Async Runtime & Crossbeam Channels — Rmpc uses Tokio for async MPD I/O and Crossbeam for inter-task communication; understanding spawn patterns, channels, and async/await is critical for fixing concurrency bugs or adding new async features
• Lua Scripting via mlua — The rmpcd daemon embeds Lua 5.5 for user hooks and scripting; understanding mlua's Lua-to-Rust bindings, error handling, and async context is needed to add or debug Lua integration
• RON (Rusty Object Notation) Serialization — All user configuration and themes are serialized as RON files (assets/example_config.ron, example_theme.ron); understanding RON syntax and serde deserialization is needed to add new config keys or validate user input
• D-Bus Integration (Zbus Crate) — Rmpc uses Zbus for D-Bus communication (likely for system notifications or MPRIS protocol support); understanding D-Bus object paths, methods, and signals is needed for system integration features

• ncmpcpp/ncmpcpp — The spiritual predecessor and primary inspiration for rmpc's feature set and three-column interface design; users migrating from ncmpcpp are rmpc's target audience
• ranger/ranger — File manager that inspired rmpc's ranger/lf-like three-column browser UX for navigating the music library hierarchically
• MusicPlayerDaemon/MPD — The core daemon that rmpc is a client for; understanding MPD's protocol and command set is essential to contributing to rmpc-mpd
• ratatui-org/ratatui — The TUI framework powering rmpc's terminal UI; contributors working on rendering, layout, or widgets need to understand ratatui architecture
• gokcehan/lf — Another file manager with a ranger-like UX that influenced rmpc's library browser design philosophy

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 comprehensive integration tests for rmpc-mpd command parsing

The rmpc-mpd crate has individual command modules (current_song.rs, status.rs, playlist_info.rs, etc.) but lacks integration tests validating end-to-end parsing of MPD protocol responses. With the test fixtures already in place (rmpc-mpd/src/tests/fixtures/), this is a high-value addition to prevent regressions when MPD protocol changes or when adding new commands.

• [ ] Create rmpc-mpd/src/tests/integration_tests.rs with test cases for each command module in rmpc-mpd/src/commands/
• [ ] Add fixtures for various MPD server responses (error cases, edge cases, empty responses) in rmpc-mpd/src/tests/fixtures/
• [ ] Test parsing of complex responses from commands like list.rs, list_all.rs, and lsinfo.rs with realistic MPD output
• [ ] Add CI workflow step in .github/workflows/ci.yml to run these integration tests separately

Add missing unit tests for rmpc-shared/src/env.rs and environment configuration

The rmpc-shared crate provides shared functionality but rmpc-shared/src/env.rs appears to have no corresponding test file. Environment variable handling is critical for configuration and portability. Adding tests here prevents bugs in config path resolution, default values, and environment variable parsing.

• [ ] Create rmpc-shared/src/tests/mod.rs and rmpc-shared/src/tests/env.rs with unit tests
• [ ] Test various environment variable scenarios (set, unset, invalid values) for configuration paths
• [ ] Add test cases for default fallback behavior when environment variables are missing
• [ ] Verify tests run in CI by checking .github/workflows/ci.yml includes rmpc-shared test step

Add GitHub Action workflow for automated dependency updates and security audits

The workspace has significant dependencies (crossterm, ratatui, tokio, zbus, mlua, etc.) defined in Cargo.toml with pinned versions. There is no visible GitHub workflow for periodic dependency audits or security scanning. This is valuable for maintaining security posture and catching breaking changes early.

• [ ] Create .github/workflows/security-audit.yml using cargo-audit or cargo-deny to scan for known vulnerabilities
• [ ] Add .github/workflows/dependency-check.yml to validate workspace dependencies in rmpc-mpd/, rmpc-shared/, rmpc/, and rmpcd/
• [ ] Configure dependabot via .github/dependabot.yml to auto-create PRs for dependency updates with changelog checking
• [ ] Update CONTRIBUTING.md to document the new security/dependency workflows for contributors

• Add missing MPD command tests: rmpc-mpd/src/commands/ has many command modules (decoders.rs, lsinfo.rs, list_mounts.rs) but no visible test files in the repo listing. Write integration tests for 3-5 command parsers to validate response parsing.
• Document config schema: assets/example_config.ron is a good start, but rmpc users need a dedicated configuration guide page or inline documentation in config.rs. Create a CONFIG.md file mapping every RON key to its effect with examples.
• Add theme variant presets: assets/example_theme.ron shows one theme, but there's no evidence of built-in presets (dark, light, monokai, etc.). Add 3-5 pre-defined themes as .ron files and a --list-themes CLI flag to enumerate them.

• Medium · Vendored Lua dependency with potential security risks — Cargo.toml (workspace.dependencies) - mlua = { version = "0.11.6", features = ["lua55", "vendored", ...]}. The mlua crate is configured with 'vendored' feature, which bundles Lua 5.5 directly into the binary. This approach may complicate security updates and vulnerability tracking for the embedded Lua runtime. Lua scripts loaded by rmpcd (as seen in assets/rmpcd/example_init.lua) could be a potential attack vector if user-provided scripts are executed without proper sandboxing. Fix: 1) Monitor Lua security advisories closely. 2) Implement strict script validation and sandboxing for rmpcd. 3) Document security implications of loading external Lua scripts. 4) Consider allowing only signed scripts or restricting script paths to trusted directories.
• Medium · Potential unsafe terminal image protocol implementations — rmpc/src/config/album_art.rs and related image handling code. The application supports multiple terminal image protocols (Kitty, Sixel, Iterm2) and ueberzuggpp. These implementations may have parsing vulnerabilities when handling untrusted image data. Malformed images could potentially trigger buffer overflows or parsing exploits, especially given the complexity of these protocols. Fix: 1) Validate and sanitize all image data before processing. 2) Use fuzzing to test image parsing with malformed inputs. 3) Implement strict bounds checking in image protocol parsers. 4) Consider using well-audited image libraries with security track records. 5) Add file size limits for downloaded album art.
• Medium · Use of 'walkdir' without path traversal validation — Cargo.toml (walkdir = "2.5.0") and rmpc/src/config/ files. The codebase includes walkdir (0.2.5.0) which is used for filesystem operations. If user-supplied paths or MPD playlist entries are not properly validated before being passed to walkdir, directory traversal attacks could occur, especially in the context of loading user configurations or playlists. Fix: 1) Validate all user-supplied file paths before filesystem operations. 2) Use canonicalize() and ensure paths stay within expected directories. 3) Implement a whitelist of allowed directories. 4) Add security tests for path traversal attempts.
• Medium · Insecure default configuration and script execution — assets/rmpcd/example_init.lua and rmpcd crate. The example_init.lua in assets/rmpcd allows arbitrary Lua script execution. If users copy this as-is or if default configurations allow loading untrusted scripts, malicious Lua code could be executed with user privileges. The rmpcd daemon could be exploited if it loads scripts without proper validation. Fix: 1) Document that example configs are for reference only. 2) Require explicit user consent before loading scripts. 3) Implement a script verification/signing mechanism. 4) Run scripts in a restricted execution environment. 5) Log all script executions for audit purposes.
• Low · Dependency on external process execution (which crate) — Cargo.toml (which = "8.0.0"). The 'which' crate (8.0.0) is used to locate external binaries. If external processes like ueberzuggpp are executed without proper input validation or with user-controlled arguments, command injection could occur. Fix: 1) Validate all arguments passed to external processes. 2) Use subprocess APIs that avoid shell interpretation (which the crate likely does). 3) Implement allowlists of safe external programs. 4) Log external process execution for debugging and security monitoring.
• Low · JSON parsing without depth limits — Cargo.toml (serde_json = "1.0.149"). The serde_json dependency is used for parsing potentially untrusted data. Malformed or deeply nested JSON could cause denial-of-service through excessive memory consumption or stack exhaustion. Fix: 1) Implement recursion depth limits during JSON parsing. 2) Set maximum JSON size limits. 3) Use serde custom deserializers to enforce constraints. 4) Test with deeply nested or large JSON payloads.
• Low · Potential information disclosure through error messages — undefined. The codebase uses anyhow and thiserror for Fix: undefined

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

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

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/mierak/rmpc 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.

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

What it runs against: a local clone of mierak/rmpc — 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 mierak/rmpc | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mierak/rmpc. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mierak/rmpc.git
#   cd rmpc
#
# 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 mierak/rmpc and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause 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 "rmpc/src/core/client.rs" \\
  && ok "rmpc/src/core/client.rs" \\
  || miss "missing critical file: rmpc/src/core/client.rs"
test -f "rmpc/src/config/mod.rs" \\
  && ok "rmpc/src/config/mod.rs" \\
  || miss "missing critical file: rmpc/src/config/mod.rs"
test -f "rmpc-mpd/src/mpd_client.rs" \\
  && ok "rmpc-mpd/src/mpd_client.rs" \\
  || miss "missing critical file: rmpc-mpd/src/mpd_client.rs"
test -f "rmpc/src/config/keys/actions.rs" \\
  && ok "rmpc/src/config/keys/actions.rs" \\
  || miss "missing critical file: rmpc/src/config/keys/actions.rs"
test -f "rmpc/Cargo.toml" \\
  && ok "rmpc/Cargo.toml" \\
  || miss "missing critical file: rmpc/Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/mierak/rmpc"
  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).

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