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/pythops/bluetui 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.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 24+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• GPL-3.0 licensed
• CI configured
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 pythops/bluetui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pythops/bluetui.

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.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.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/app.rs" \\
  && ok "src/app.rs" \\
  || miss "missing critical file: src/app.rs"
test -f "src/bluetooth.rs" \\
  && ok "src/bluetooth.rs" \\
  || miss "missing critical file: src/bluetooth.rs"
test -f "src/handler.rs" \\
  && ok "src/handler.rs" \\
  || miss "missing critical file: src/handler.rs"
test -f "src/ui.rs" \\
  && ok "src/ui.rs" \\
  || miss "missing critical file: src/ui.rs"

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

bluetui is a Linux TUI (terminal user interface) for discovering, pairing, and managing Bluetooth devices via the BlueZ daemon. It provides a real-time, keyboard-navigable interface to control Bluetooth adapters, pair/unpair devices, manage trusted/favorite status, and handle pairing authentication requests (PIN/passkey entry) without leaving the terminal. Single-crate Rust binary structured as src/{lib,main,cli,app,handler,event,bluetooth,rfkill,config,...}.rs with modular request handlers (src/requests/) for pairing prompts (confirmation, PIN/passkey entry/display), device state (src/favorite.rs, src/alias.rs), and UI rendering via ratatui. Event-driven architecture: crossterm streams raw terminal events, tokio::spawn handles async DBus operations, and async-channel coordinates between TUI and Bluetooth threads.

Linux power users and system administrators who manage Bluetooth devices from the command line or prefer TUI over GNOME Settings/systemd-qt-bluetooth-manager. Developers integrating Bluetooth management into headless or minimal Linux systems.

Actively developed and production-ready. The project is at version 0.8.1 with packaging in Arch Linux (extra repo) and Gentoo, indicating stable adoption. CI pipeline is present (ci.yaml, release.yaml), snapshot tests are in place, and the codebase enforces Clippy lints. However, pre-1.0 versioning suggests API surfaces may still shift.

Low risk operationally but tied to BlueZ stability. Heavy dependency on bluer (0.17) for DBus Bluetooth daemon communication—upstream changes could break pairing flows. Single-maintainer appearance (pythops) and relatively small issue backlog suggest healthy but narrow resource allocation. No apparent breaking changes in recent activity, but pre-1.0 versioning allows them.

No specific active PR or milestone data visible in the file list, but the presence of workflow files (ci.yaml, release.yaml) and recent snapshot tests indicates ongoing maintenance. The config system (src/config.rs, src/cli.rs) supports keybinding customization and layout modes, suggesting the focus is on UX polish and extensibility rather than major feature work.

git clone https://github.com/pythops/bluetui
cd bluetui
cargo build --release
./target/release/bluetui

Or install via Arch: pacman -S bluetui, or crates.io: cargo install bluetui. Requires BlueZ installed on the system (bluez package).

Daily commands:

cargo run --release

Or after building: ./target/release/bluetui. No dev server; this is a native TUI that runs as a foreground process. Must have BlueZ daemon (bluetoothd) running and user must be in bluetooth group or have dbus permissions.

• src/main.rs — Application entry point; initializes the async runtime, TUI setup, and coordinates the main event loop between UI and Bluetooth backend.
• src/app.rs — Core application state machine; manages all UI screens, navigation, and application-level state transitions—essential for understanding control flow.
• src/bluetooth.rs — Bluetooth adapter and device management via the bluer crate; abstracts all D-Bus interactions with BlueZ daemon and is critical for all device operations.
• src/handler.rs — Event handler that bridges user input (keyboard/mouse) to app state mutations; essential for understanding how the TUI responds to user actions.
• src/ui.rs — Ratatui widget rendering layer; responsible for converting app state into terminal UI components—every visual change flows through here.
• src/agent.rs — Agent service spawns and manages long-lived async tasks for device discovery, pairing, and D-Bus signal handling; critical concurrency layer.
• Cargo.toml — Project manifest with all dependencies; bluer, ratatui, tokio, and crossterm are the pillars of this TUI Bluetooth manager.

Add a new TUI screen (e.g., Device Settings)

1. Add a new variant to the Screen enum in src/app.rs (e.g., DeviceSettings) (src/app.rs)
2. Add a corresponding render function in src/ui.rs with pattern render_device_settings() that returns a Frame widget (src/ui.rs)
3. Add input handling in src/handler.rs to capture keys/input for the new screen and mutate app state accordingly (src/handler.rs)
4. Add help text in src/help.rs documenting keybindings for the new screen (src/help.rs)

Add a new Bluetooth device operation (e.g., Set Device Volume)

1. Add a new method to struct Adapter in src/bluetooth.rs (e.g., pub async fn set_device_volume()) that calls the appropriate BlueZ D-Bus method via bluer (src/bluetooth.rs)
2. Add an Event variant in src/event.rs to represent task completion (e.g., BluetoothVolumeSet) (src/event.rs)
3. Spawn the async operation in src/handler.rs or src/agent.rs depending on whether it's user-initiated or a daemon-like task (src/handler.rs)
4. Handle the event result in the main loop (in src/main.rs or event matching logic) to update app state and render feedback (src/main.rs)

Add a new D-Bus request type (e.g., AuthorizeService)

1. Create a new request handler file src/requests/authorize_service.rs with a struct implementing the request callback interface (src/requests/authorize_service.rs)
2. Register the handler in src/agent.rs by adding a variant to the request enum and hooking it into the D-Bus signal listener (src/agent.rs)
3. Add a screen variant in src/app.rs (e.g., RequestAuthorizeService) and a corresponding render function in src/ui.rs (src/app.rs)
4. Add input handling in src/handler.rs to approve/deny the request and send the response back via D-Bus (src/handler.rs)

Add a new configuration option

1. Add a field to the config struct in src/config.rs with serde derive annotations (src/config.rs)
2. Load and apply the config in src/app.rs during initialization or in src/handler.rs on config reload (src/app.rs)
3. If user-configurable, add a UI screen/dialog in src/ui.rs and input handling in src/handler.rs (src/ui.rs)

• Tokio async runtime — Non-blocking I/O for D-Bus calls and Bluetooth device discovery; allows responsive TUI while waiting for BlueZ daemon responses.
• Bluer crate — High-level Rust bindings to BlueZ D-Bus API; eliminates manual D-Bus serialization and provides type-safe Bluetooth abstractions.
• Ratatui — Declarative TUI widget library; simplifies terminal rendering and enables responsive, themeable UI without raw ANSI codes.
• Crossterm — Cross-platform terminal event handling; provides keyboard/mouse input and raw mode management without platform-specific code.
• async-channel — Thread-safe event channels for decoupling TUI event loop from async Bluetooth tasks; ensures clean separation of concerns.

• Single-threaded async event loop with Tokio runtime

  • Why: Simplifies state management and avoids complex locking patterns in the TUI.
  • Consequence: Long-running synchronous operations (if any) would block the entire UI; must ensure all I/O is async or delegated to agent tasks.

• D-Bus agent pattern for PIN/passkey requests

  • Why: BlueZ requires a registered D-Bus agent service to handle pairing callbacks; this is the only way to intercept and present pairing dialogs.
  • Consequence: Adds complexity in signal listening and D-Bus method response; requires careful error handling if the TUI crashes during a pairing flow.

• Stateful UI state machine (Screen enum) in app.rs

  • Why: Centralizes navigation logic and prevents inconsistent state; makes testing and state debugging easier.
  • Consequence: Adding new screens or state transitions requires coordinated changes across app.rs, handler.rs, and ui.rs; no automatic state derivation.

• RFKill integration for Bluetooth toggle

  • Why: Provides system-level radio control; more reliable than D-Bus-only control on some hardware.
  • Consequence: Requires elevated privileges or udev rules; failure to access /sys/class/rfkill will silently prevent Bluetooth toggle.

• Cross-platform

1. BlueZ daemon must run: bluetui will fail silently if bluetoothd isn't active; no clear user-facing error. 2) DBus permissions: User must be in bluetooth group or have explicit dbus policy; errors manifest as DBus permission denied, not caught gracefully. 3) Nerd font required: Icons render as garbage without nerd fonts installed; README notes this but doesn't auto-detect. 4) Config path is hardcoded: $HOME/.config/bluetui/config.toml or -c flag; no env var override like $BLUETUI_CONFIG. 5) Pairing prompt context: src/agent.rs hooks into BlueZ agent callbacks; if bluetui crashes mid-pairing, the device may be left in a pending state requiring manual bluetoothctl cleanup.

• BlueZ Agent Protocol (DBus) — bluetui implements the BlueZ Agent interface (src/agent.rs) to intercept pairing callbacks; understanding RequestConfirmation, DisplayPasskey, etc. is critical to modify auth flows.
• Async-aware Event Channels (async-channel, tokio::mpsc) — bluetui uses async-channel and tokio channels to decouple terminal input (crossterm thread) from Bluetooth DBus callbacks; misunderstanding this leads to deadlocks or dropped events.
• Snapshot Testing (insta crate) — Test assertions in src/requests/ use insta snapshots instead of manual assertions; modifying UI will auto-regenerate .snap files; important to understand before changing request prompts.
• DBus Introspection & Method Calls — src/bluetooth.rs uses bluer to make async DBus calls to org.bluez services; understanding DBus paths (e.g., /org/bluez/hci0/dev_XX) helps debug device discovery.
• Terminal State Machines (Ratatui App Pattern) — src/app.rs models the TUI as a state machine with screens (Adapters, PairedDevices, NewDevices, Requests); understanding StatefulWidget trait and focus management prevents UI regressions.
• TOML Configuration Deserialization — src/config.rs uses serde + toml to parse keybindings; adding new config fields requires understanding serde derive macros and TOML nesting.
• Cross-platform Terminal Control (crossterm) — bluetui uses crossterm::event::EventStream for non-blocking keyboard input; understanding RawMode, event queue, and terminal size queries helps with edge cases like window resize.

• pythops/impala — Sister project for WiFi management on Linux; same author, same TUI patterns with ratatui and tokio, complementary to bluetui
• bluez/bluez — Official BlueZ repository; source of truth for DBus APIs and agent protocol that bluetui implements via bluer crate
• fujiapple852/trippy — Reference TUI codebase also using ratatui + crossterm + tokio; shows patterns for event-driven terminal UI at scale
• ratatui/ratatui — Core TUI rendering framework used by bluetui; understanding its widget API (Block, List, Paragraph) is essential to modify UI layout
• zacchaeus/bluer — The bluer crate that wraps BlueZ DBus—bluetui's direct bridge to Bluetooth; inspect this for available device/adapter methods

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 unit tests for src/bluetooth.rs module

The bluetooth.rs module is a core component handling BlueZ D-Bus interactions, but there are no snapshot tests or unit tests visible in src/snapshots/ for it. Given that the project already uses insta for snapshot testing (see requests/snapshots and snapshots directories), adding tests for bluetooth device discovery, pairing, connection state management, and adapter operations would improve reliability and catch regressions early.

• [ ] Create unit tests in src/bluetooth.rs using #[cfg(test)] for device discovery and filtering logic
• [ ] Add snapshot tests using insta crate for Bluetooth adapter state representations
• [ ] Test edge cases: no adapters available, device pairing failures, connection timeouts
• [ ] Run 'cargo test' and verify snapshots are generated in src/snapshots/

Add unit tests for src/config.rs TOML parsing and validation

The config.rs module handles user configuration parsing from TOML files (as seen in Cargo.toml dependencies with 'toml = 0.9'), but no tests are visible for config validation, default values, or invalid configuration handling. This is critical for user experience when configs are malformed.

• [ ] Create test cases in src/config.rs for valid/invalid TOML configurations
• [ ] Add tests for default configuration fallback behavior
• [ ] Test parsing of configuration file paths via dirs crate (seen in dependencies)
• [ ] Add snapshot tests for configuration structure validation errors

Create missing help/UI snapshot tests for remaining screens (Adapter, NewDevices, PairedDevices)

The project has extensive snapshot tests for request screens (confirmation, passkey entry, etc.) at multiple terminal widths (80, 81, 120, 121), but src/snapshots/ shows help tests only exist for some screens. The file list shows missing test snapshots for complete coverage of Adapter, NewDevices, and PairedDevices screens at all width variants.

• [ ] Review src/help.rs to identify all Screen variants needing help text tests
• [ ] Add snapshot tests for each missing screen variant at widths: 80, 81, 120, 121
• [ ] Run snapshot tests: 'cargo test --lib help::tests' and commit .snap files
• [ ] Verify all Screen enum variants have corresponding snapshot files in src/snapshots/

• Add unit tests for src/alias.rs similar to snapshot tests in src/requests/snapshots/—currently no dedicated test file for device renaming logic.
• Implement env var override for config path (e.g., $BLUETUI_CONFIG) in src/config.rs to improve portability on non-standard home layouts.
• Add a --list or --json output mode to CLI (src/cli.rs) for scripting device discovery without spawning the TUI; extends usability for automation.

The bluetui project demonstrates generally good security practices as a TUI application with limited external attack surface. However, it has one critical build configuration issue (invalid Rust edition) that must be fixed immediately. The main security concerns revolve around D-Bus interactions with the underlying Bluetooth system, which require careful handling of privileged operations. The project uses reasonably secure dependencies but lacks explicit security documentation, dependency auditing in CI/CD, and documented guidelines for secure usage. Recommendations focus on fixing the build configuration, adding security documentation, implementing input validation, and setting up automated dependency scanning.

• High · Invalid Rust Edition in Cargo.toml — Cargo.toml. The Cargo.toml specifies edition = "2024" which is not a valid Rust edition. Valid editions are 2015, 2018, and 2021. This will cause build failures and suggests the project has not been properly tested or built, potentially masking other security issues. Fix: Change edition to a valid value: edition = "2021" (or "2018" for older compatibility)
• Medium · Potential Unsafe DBus Interaction — Cargo.toml (libdbus-sys dependency), src/bluetooth.rs, src/agent.rs. The codebase uses bluer (Bluetooth library) with libdbus-sys as a dependency. The libdbus-sys is a low-level FFI binding to the D-Bus C library. Improper handling of D-Bus messages could lead to security issues like privilege escalation, information disclosure, or denial of service attacks. Fix: Ensure all D-Bus method calls are properly validated. Use allowlists for authorized D-Bus calls. Implement proper error handling for D-Bus responses. Consider using higher-level safe wrappers where available.
• Medium · Vendored C Library Dependencies — Cargo.toml (libdbus-sys feature). The libdbus-sys dependency uses vendored = true for the C library. While this improves portability, it means the project bundles an external C library (libdbus) which may not receive regular security updates and could lag behind upstream patches. Fix: Regularly monitor upstream libdbus releases for security patches. Consider using system libdbus when possible. Document the vendored approach in security documentation.
• Medium · Insufficient Input Validation in CLI/Config — src/cli.rs, src/config.rs. The project uses clap for CLI parsing and toml for configuration files. Without explicit validation in src/cli.rs and src/config.rs, user-supplied input from both CLI arguments and configuration files could potentially be processed unsafely, leading to unexpected behavior or vulnerabilities. Fix: Implement strict input validation for all CLI arguments and config file values. Define expected formats and ranges. Use type-safe parsing. Validate file paths to prevent directory traversal attacks.
• Low · Missing Security Headers in Documentation — Readme.md, src/main.rs documentation. The README and project documentation do not explicitly mention security considerations, prerequisites for secure usage (e.g., running with minimal privileges), or known limitations regarding Bluetooth security. Fix: Add a security section to the README documenting: required permissions, security considerations for Bluetooth operations, how the tool handles sensitive data (PINs, passphrases), and recommendations for secure deployment.
• Low · No Dependency Auditing Configured — .github/workflows/ci.yaml. No evidence of dependency auditing tools (cargo-audit, cargo-deny) configured in CI/CD pipeline (.github/workflows/ci.yaml). This means vulnerable dependencies might not be caught during development. Fix: Configure cargo-audit or cargo-deny in the CI/CD pipeline to automatically check for known vulnerabilities in dependencies.
• Low · Potential Information Disclosure in Error Messages — src/lib.rs, src/main.rs, error handling throughout codebase. Using anyhow for error handling without explicit sanitization could lead to verbose error messages being displayed to users, potentially leaking system information or internal paths. Fix: Implement custom error types with user-friendly messages. Log detailed errors server-side only. Ensure error messages don't expose file paths, system information, or internal implementation details to end users.

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.