Findarr

Chat your way to your next favorite band.

Findarr is a self-hosted music discovery app. Instead of scrolling algorithmic playlists, you have a conversation: tell it what you've been listening to, dig into why an artist clicks for you, and get recommendations that actually fit — delivered as cards right in the chat, with listening links so you can check each one out immediately.

What it's like to use

You might start with something like "I've really been digging Moon Duo lately" and end up twenty minutes later with a fresh batch of krautrock-adjacent deep cuts, having figured out along the way that what you actually love is hypnotic repetition with fuzz on top.

• It learns your taste. As you chat and react, Findarr builds a running analysis of what you like and why — not just a list of bands, but the qualities that connect them. Open the Taste Profile panel any time to see what it thinks of you.
• Suggestions come as cards. Each one has genre tags, a one-line reason it fits you, and search links for Spotify, YouTube, Last.fm, and Bandcamp.
• React with one click. Like, Dislike, Meh, Already Have — every reaction sharpens future suggestions. (There's even a button for calling out artists that don't exist. AI, you know.)
• It knows your collection. Connect your Plex server and Findarr syncs your music library, so it never recommends something you already own — and it can reason about what you have ("what's in my library that sounds like this?").
• Conversations are saved. Pick up an old thread from the History panel whenever you want.

Setting it up

You'll need Docker with Compose, and an Anthropic API key (the chat runs on Claude — you pay Anthropic directly for usage).

git clone <this repo> && cd findarr
cp .env.example .env
# edit .env: set ANTHROPIC_API_KEY (and LASTFM_API_KEY — see below)
docker compose up -d

Open http://localhost:8088 and say hi.

Recommended: a Last.fm API key

Grab a free key at last.fm/api/account/create and put it in .env as LASTFM_API_KEY. It gets you two things: artist photos on suggestion cards, and much better genre data for your synced collection (Plex's own genre tags are vague; Last.fm's community tags are what make "what do I own in this genre?" actually work).

Optional: connect Plex

Open Settings (gear icon) in the app, enter your Plex server URL and token, hit Test Connection, then Sync Music Library. The first sync tags your whole collection via Last.fm, so it can take a couple of minutes — after that, syncs only process new artists.

Plex on the same machine, but the connection times out? If Plex runs natively on the Docker host, your firewall may be blocking traffic from Docker's network to it. On ufw: sudo ufw allow 32400/tcp (or scope it to Docker's subnet if you prefer).

Environment variables

Variable	Default	Description
ANTHROPIC_API_KEY	—	Required. Claude API key
LASTFM_API_KEY	—	Recommended. Artist images + collection genre tags
DATABASE_URL	bundled SQLite	Only change if you know you want to
SECRET_KEY	—	Random secret (openssl rand -hex 32), reserved for future use
LOG_LEVEL	info	debug for verbose chat/tool logging

Everything is stored in a single SQLite database under ./data/ — back that up and you've backed up your taste profile, library, and conversations.

Running from source (development)

Requires Python 3.12+ with uv and Node.js 22+.

uv sync
cp .env.example .env        # set ANTHROPIC_API_KEY
uv run uvicorn app.main:app --reload    # backend on :8000

# second terminal:
cd frontend && npm install && npm run dev    # frontend on :5173

Open http://localhost:5173. Architecture notes for contributors live in CLAUDE.md.

License

MIT — see LICENSE.