GO — Healthy across the board

• Last commit 1d ago
• 16 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

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

Psst is a lightweight, native Spotify client written in Rust using the Druid GUI framework, eliminating Electron overhead while delivering fast playback across Windows, Linux, and macOS. It handles Spotify's proprietary encryption (Shannon codec), CDN streaming, audio decoding (via Symphonia), and OAuth authentication—replacing the official Spotify app for power users who want native performance and transparency. Workspace monorepo with three members: psst-core (724KB Rust, audio + encryption + networking), psst-cli (CLI wrapper), and psst-gui (Druid-based UI, not shown in file list but implied). Core splits into audio/ (decode, decrypt, resample, output via CPAL/Cubeb), connection/ (Diffie-Hellman, Shannon codec), cdn.rs (streaming), and player/ (playback state machine).

Spotify Premium subscribers and Rust developers who want a minimal-footprint music client without browser bloat; contributors interested in audio streaming protocols, cryptography (Diffie-Hellman key exchange), and cross-platform native GUI development in Rust.

Actively developed but early-stage: the README explicitly states 'very early in development, lacking in features, stability, and general user experience.' CI/CD via GitHub Actions is solid (auto-releases on main), but the single-maintainer jpochyla and sparse test coverage in psst-core suggest caution for production use. Best viewed as a well-engineered hobbyist/learning project rather than a Spotify app replacement.

Single maintainer (jpochyla) is the primary risk; no obvious governance handoff plan. Heavy dependency on third-party audio libs (Symphonia, libsamplerate, CPAL/Cubeb for output) means upstream breakage can cascade. Spotify's API and encryption scheme are undocumented—reverse-engineered integration is fragile if Spotify changes protocols. No formal test suite visible in file list, only ad-hoc validation.

Cannot determine from file list alone (no commit history provided), but GitHub Actions build pipeline is live, suggesting ongoing CI maintenance. Desktop builds for Linux (x86_64 + aarch64), macOS, Windows, and Debian packages are automated—implying recent attention to packaging and cross-platform stability.

git clone https://github.com/jpochyla/psst.git
cd psst
rustup update stable  # Ensure Rust 1.65.0+
# Linux (Debian/Ubuntu): sudo apt-get install libssl-dev libgtk-3-dev libcairo2-dev libasound2-dev
# Linux (RHEL/Fedora): sudo dnf install openssl-devel gtk3-devel cairo-devel alsa-lib-devel
cargo build --release
./target/release/psst-gui  # Run the GUI, or psst-cli for CLI

Daily commands:

cargo run --release -p psst-gui          # GUI client
cargo run --release -p psst-cli -- play  # CLI (play subcommand, signature unknown)
cargo build --release -p psst-core       # Core library tests (if any)

• psst-core/src/lib.rs — Core library root that exports audio, session, player, and metadata systems—all new contributors must understand this module graph
• psst-core/src/session/mod.rs — Spotify session authentication and token management—foundational for all API communication and playback
• psst-core/src/player/mod.rs — Main player state machine and playback control logic—critical for understanding how tracks are queued and played
• psst-core/src/audio/source.rs — Audio frame source and streaming pipeline—essential for understanding decryption, decoding, and output flow
• psst-gui/src/main.rs — GUI entry point using Druid framework—must-read for understanding the entire UI initialization and command dispatch
• psst-gui/src/data/ctx.rs — Application context data structure managing session, player, and UI state—core data model for GUI logic
• psst-core/src/metadata.rs — Spotify metadata models (tracks, albums, artists, playlists) and deserialization—essential for data structures throughout the app

Add a New Playback Control Command

1. Add command variant to the Command enum in psst-gui/src/cmd.rs (psst-gui/src/cmd.rs)
2. Add handler in the button/widget controller, likely in psst-gui/src/controller/playback.rs, to dispatch the command (psst-gui/src/controller/playback.rs)
3. Implement command execution in psst-gui/src/controller/on_command.rs or on_command_async.rs to call player methods (psst-gui/src/controller/on_command.rs)
4. Add corresponding method to Player struct in psst-core/src/player/mod.rs to queue the action (psst-core/src/player/mod.rs)
5. Update player worker in psst-core/src/player/worker.rs to handle the new command variant (psst-core/src/player/worker.rs)

Add a New Metadata Type (e.g., Podcast Show)

1. Add Serde struct definition in psst-core/src/metadata.rs with correct Spotify API schema (psst-core/src/metadata.rs)
2. Create corresponding UI data model in psst-gui/src/data/show.rs (or equivalent) (psst-gui/src/data/show.rs)
3. Add Mercury protocol request in psst-core/src/session/mod.rs to fetch this metadata type (psst-core/src/session/mod.rs)
4. Implement a Lens/derive Clone in the UI data model for Druid reactive updates (psst-gui/src/data/mod.rs)
5. Add a new view widget in psst-gui/src (typically a new widget file) to render this metadata in the UI (psst-gui/src/main.rs)

Add a New Search Filter or Query Parameter

1. Extend the search query parameters in psst-core/src/metadata.rs or the session Mercury call (psst-core/src/session/mod.rs)
2. Add new field to Search data struct in psst-gui/src/data/search.rs (psst-gui/src/data/search.rs)
3. Add input widget (textbox, dropdown) to the search UI view in psst-gui/src/main.rs or a dedicated view file (psst-gui/src/main.rs)
4. Wire the widget to update the Search data state via a Lens and command dispatch in a controller (psst-gui/src/controller/on_update.rs)

Add Cross-Platform Audio Output (new backend)

1. Create a new module file (e.g., psst-core/src/audio/output/new_backend.rs) implementing the AudioOutput trait (psst-core/src/audio/output/mod.rs)
2. Add feature flag and conditional compilation in Cargo.toml (psst-core/Cargo.toml)
3. Export the new implementation in psst-core/src/audio/output/mod.rs and update factory logic (psst-core/src/audio/output/mod.rs)
4. Update platform detection logic in psst-core/src/system_info.rs if needed for OS-specific selection (psst-core/src/system_info.rs)

Spotify credentials: OAuth flow requires valid Spotify app credentials (client ID/secret) not bundled in repo—must be provided at runtime. Linux backend selection: GTK is default; switching to X11 requires feature flag and different GTK3 deps. macOS/Windows native GUI libs: Druid abstracts them, but undocumented platform-specific quirks likely exist. Audio output: CPAL and Cubeb backends compete; CPAL is fallback on some platforms—test both if audio breaks. Symphonia codec support: Only formats compiled into Symphonia are playable; MP3 or unsupported codecs will fail silently. Cross-compilation via Cross: Cross.toml exists but build matrix for aarch64 may require special setup (see README notes on platform-specific builds).

• Shannon Cipher — Psst's entire encrypted communication with Spotify uses this stream cipher; understanding Shannon's key schedule and IV handling is mandatory for modifying connection/shannon_codec.rs.
• Diffie-Hellman Key Exchange — Establishes the shared secret for Shannon cipher initialization in psst-core/src/connection/diffie_hellman.rs; core to session security and protocol handshake.
• Ogg Vorbis Audio Codec — Spotify streams audio as encrypted Ogg Vorbis frames; Symphonia decodes these in psst-core/src/audio/decode.rs—knowing codec structure helps debug decode failures.
• Audio Resampling (SRC) — psst-core/src/audio/resample.rs uses libsamplerate for sample-rate conversion (e.g., 96 kHz to 48 kHz); critical for devices with mismatched output rates.
• CPAL (Cross-Platform Audio Library) Abstraction — psst-core/src/audio/output/cpal.rs wraps platform audio I/O (ALSA on Linux, CoreAudio on macOS, WASAPI on Windows); changes to output logic require CPAL API familiarity.
• OAuth 2.0 Implicit Flow — psst-core/src/oauth.rs handles Spotify token acquisition; understanding redirect URIs, scopes, and token refresh is needed for auth changes.
• Actor Model Concurrency — psst-core/src/actor.rs likely uses message-passing for async audio/network I/O; critical for understanding how player state, CDN fetches, and UI updates are synchronized.

• librespot-org/librespot — Rust Spotify client library with similar reverse-engineered protocol implementation; librespot can be embedded or forked if Psst's connection logic needs reference or fallback.
• ncspot/ncspot — Terminal-based Spotify client in Rust also using librespot backend; demonstrates alternative UI (TUI vs native GUI) on the same Spotify integration foundation.
• Spotlistr/Spotlistr — Web-based playlist manager for Spotify; complementary tool for users of Psst who need batch operations and data export.
• PointerToNowhere/spotify-lib-web-api — Rust bindings to Spotify Web API; Psst uses protocol reverse-engineering, but this repo shows the official API alternative for metadata/user queries if Psst ever needs it.
• linebender/druid — The GUI framework used by Psst; upstream repo for all widget behavior, styling, and cross-platform event handling—essential for UI contributors.

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 integration tests for psst-core session and authentication modules

The psst-core crate has critical session management code (psst-core/src/session/) handling OAuth, audio keys, and Mercury protocol, but there are no visible integration tests. Given this is a Spotify client, authentication reliability is critical. Adding tests would catch regressions in login flows, token refresh, and session establishment before they reach users.

• [ ] Create psst-core/tests/integration/ directory with session test module
• [ ] Add tests for psst-core/src/session/login5.rs covering successful login and error cases
• [ ] Add tests for psst-core/src/session/access_token.rs token refresh logic
• [ ] Add tests for psst-core/src/session/audio_key.rs key acquisition
• [ ] Document test setup requirements in CONTRIBUTING.md (if missing)

Add GitHub Actions workflow for cross-platform ARM builds and release artifacts

The repo has .github/workflows/build.yml but the file structure shows Cross.toml exists (for cross-platform compilation), suggesting ARM/ARM64 support is intended. However, there's no visible workflow for building ARM releases (Linux ARM64, macOS ARM64). This blocks users on Apple Silicon and ARM Linux from getting native builds.

• [ ] Review current .github/workflows/build.yml to understand existing matrix strategy
• [ ] Extend build matrix in build.yml to include aarch64-unknown-linux-gnu and aarch64-apple-darwin targets
• [ ] Configure Cross.toml for proper ARM cross-compilation settings if needed
• [ ] Add ARM release artifact uploads to GitHub Releases matching existing platform naming convention
• [ ] Test locally with cross tool before committing

Extract audio output backend abstraction and add PulseAudio/ALSA fallback logic

psst-core/src/audio/output/ has modular backends (cpal.rs, cubeb.rs, mod.rs) but the selection logic and fallback behavior are unclear from the file structure. On Linux, users often have mismatched audio systems; adding explicit PulseAudio detection and ALSA fallback would improve compatibility. This requires documenting and potentially refactoring the backend selection in psst-core/src/audio/output/mod.rs.

• [ ] Review psst-core/src/audio/output/mod.rs to map current backend selection logic
• [ ] Add explicit PulseAudio detection before cubeb fallback in audio initialization
• [ ] Create psst-core/src/audio/output/pulseaudio.rs as new optional backend
• [ ] Update Cargo.toml with feature flags for audio backends (feature: pulseaudio, feature: cubeb, feature: cpal)
• [ ] Add documentation in README.md under a new 'Audio Backend Support' section explaining Linux platform detection

• Add unit tests to psst-core/src/audio/decrypt.rs and psst-core/src/audio/decode.rs covering edge cases (truncated frames, invalid keys, unsupported codecs)—currently no visible test coverage in those files.
• Document the Shannon cipher protocol and Diffie-Hellman flow in psst-core/src/connection/ with inline comments and a PROTOCOL.md file explaining Spotify's handshake (reverse-engineered docs are scattered; consolidate them).
• Implement a --help / usage guide for psst-cli/src/main.rs and expose player subcommands (play, pause, next, prev, search) with argument parsing (currently likely a stub).

• High · Unsafe Cryptographic Implementation in Diffie-Hellman — psst-core/src/connection/diffie_hellman.rs. The codebase implements custom Diffie-Hellman key exchange (psst-core/src/connection/diffie_hellman.rs). Custom cryptographic implementations are prone to vulnerabilities such as timing attacks, improper parameter validation, or weak random number generation. This is particularly critical for session establishment and key material derivation. Fix: Use well-established cryptographic libraries (e.g., rustls, ring) instead of custom implementations. If custom DH is necessary, undergo formal security audit and ensure constant-time operations, proper parameter validation (prime checks, generator verification), and cryptographically secure RNG.
• High · Custom Shannon Codec Implementation — psst-core/src/connection/shannon_codec.rs. Custom implementation of Shannon codec for encryption (psst-core/src/connection/shannon_codec.rs) may contain subtle cryptographic flaws. Shannon cipher implementation requires extreme precision to avoid information leakage or authentication bypass. Fix: Verify against official specifications and conduct security audit. Consider using authenticated encryption (AEAD) modes instead. Ensure proper key derivation and IV handling.
• High · Audio Decryption Module Security — psst-core/src/audio/decrypt.rs. Custom audio decryption implementation (psst-core/src/audio/decrypt.rs) handles sensitive Spotify audio stream decryption. Improper implementation could lead to key recovery, plaintext audio extraction, or replay attacks. Fix: Audit decryption logic for proper key handling, IV management, and authentication. Ensure no timing leaks in decryption process. Implement integrity checking on decrypted audio streams.
• Medium · Session Token Management — psst-core/src/session/access_token.rs, psst-core/src/session/client_token.rs, psst-core/src/session/token.rs. Multiple token handling modules (access_token.rs, client_token.rs, token.rs) manage sensitive authentication credentials. Improper token storage, transmission, or refresh logic could lead to token compromise or session hijacking. Fix: Implement secure token storage (encrypted, with appropriate permissions). Use secure random generation for tokens. Implement token expiration and refresh mechanisms. Avoid logging tokens. Use HTTPS for all token transmission.
• Medium · OAuth Implementation Review Needed — psst-core/src/oauth.rs. OAuth flow implementation (psst-core/src/oauth.rs) handles user authentication. Potential issues: improper state validation, insecure redirect URIs, or token exposure in logs/UI. Fix: Implement PKCE (Proof Key for Code Exchange) for authorization code flow. Validate state parameters properly. Use secure random generation for state tokens. Ensure redirect URIs are whitelisted. Never log or expose tokens in debug output.
• Medium · Cache Security - Plaintext Audio Storage — psst-core/src/cache.rs. Audio caching module (psst-core/src/cache.rs) may store decrypted audio streams on disk. If cache directory is world-readable or stored unencrypted, attackers could extract cached music content. Fix: Encrypt cached audio content. Set strict file permissions (0600). Consider using OS-specific secure storage APIs. Implement cache invalidation and secure deletion (overwrite before removal).
• Medium · CDN Request Security — psst-core/src/cdn.rs. CDN module (psst-core/src/cdn.rs) handles content delivery requests. Potential issues: man-in-the-middle attacks, improper certificate validation, or serving malicious content. Fix: Enforce HTTPS-only connections. Implement certificate pinning for known CDN endpoints. Validate content signatures/checksums before using. Implement secure redirect validation.
• Medium · Audio Output Abstraction - Platform-Specific Risks — psst-core/src/audio/output/cpal.rs, psst-core/src/audio/output/cub. Multiple audio output backends (cpal, cubeb) with platform-specific implementations could have varying security properties. Improper audio device access could leak audio outside intended channels. 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/jpochyla/psst 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 jpochyla/psst repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jpochyla/psst.

What it runs against: a local clone of jpochyla/psst — 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 jpochyla/psst | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "psst-core/src/lib.rs" \\
  && ok "psst-core/src/lib.rs" \\
  || miss "missing critical file: psst-core/src/lib.rs"
test -f "psst-core/src/session/mod.rs" \\
  && ok "psst-core/src/session/mod.rs" \\
  || miss "missing critical file: psst-core/src/session/mod.rs"
test -f "psst-core/src/player/mod.rs" \\
  && ok "psst-core/src/player/mod.rs" \\
  || miss "missing critical file: psst-core/src/player/mod.rs"
test -f "psst-core/src/audio/source.rs" \\
  && ok "psst-core/src/audio/source.rs" \\
  || miss "missing critical file: psst-core/src/audio/source.rs"
test -f "psst-gui/src/main.rs" \\
  && ok "psst-gui/src/main.rs" \\
  || miss "missing critical file: psst-gui/src/main.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/jpochyla/psst"
  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.