forkstify

Take back the algorithm.

A music player for Linux, wired to Spotify, that plays by branches: start from a track, let it play a few, then pick one of the directions it proposes — or let it pick — and so on. You re-choose as the music and your mood move, so you never drop out.

Streaming services recommend with an algorithm you cannot see, understand or correct. forkstify is not a smarter recommender: it is one whose every reason you can read and change. Its reasons live in text files — one TOML card per artist: tags, top tracks, typed links to other artists — in a git repository you fork, improve and share. The rule behind every feature: any automatic decision must be explainable in one sentence and changeable in one commit.

What it does

• Branches. From what is playing, three directions with their reasons — shared members, a collaboration, the same scene, a similar sound — drawn from the catalog's links first, from a vector space when the links run out. 1–3 takes one, ⏎ lets it choose.
• A comfort dial, 5 cocoon → 0 exploration: how far it strays from what you know when it chooses for you.
• It learns from what you play, silently, into learned/ — plays, likes, skips, bans — and never pushes that upstream.
• A catalog that grows. Arrive at an artist without a card and one is generated on the spot (MusicBrainz, then Deezer), with its vector, in a commit. Fix a top, draw a link: a commit too, readable, revertible.
• A fork, not a copy. Your catalog is a fork of the reference. Cu brings the reference in, Cp proposes your cards back as one pull request. What is yours is your commits.

The interface is a terminal one, driven by a vim-like grammar: f the branch, e encore, t the track, a the artist, C the catalog; space is the leader and shows what you can type. The whole table is in docs/keybindings.md, and the screens are in docs/tour.md.

What it needs

• Linux. Built and used on Omarchy; anything with ALSA should do.
• Spotify Premium. forkstify is a Spotify Connect device (librespot) and reads your library through the Web API. It is not affiliated with Spotify, and it uses an unofficial client the way the free ecosystem does — see docs/design/spotify.md.
• git, and a GitHub account if you want your catalog to be a fork you can propose from (gh makes that one keystroke).
• Nothing to build. Each release carries a Linux x86_64 binary, so there is no toolchain and no docker to install. docker is needed only to build from source — on another architecture, or to develop.

Install

As an Omarchy plugin — the repository is one, so the bar widget comes with it:

omarchy plugin add https://github.com/aropixel/forkstify.git

Then click the forkstify icon in the bar and press "Install": that is what puts the binary in place. It fetches the released one, checks it against the published SHA256SUMS, and falls back to a container build only if it cannot. Nothing tells you to do this from the terminal, so: adding the plugin is not installing forkstify.

On Arch, as a package, from a clone — this is the AUR package, served from here while AUR registration is closed:

git clone https://github.com/aropixel/forkstify.git
cd forkstify/packaging/aur/forkstify-bin && makepkg -si

From source, on another architecture or to develop — this is the one that needs docker:

bin/build                      # cargo build --release, in a container
ln -s "$PWD/target/release/forkstify" ~/.local/bin/forkstify
forkstify

To develop against Omarchy, bin/dev-install does all of that and links the clone in as the bar widget, so the plugin you see is the code you are editing.

The binary runs on the host and needs only libasound.so.2 and libstdc++.so.6. Its glibc floor is Debian 12's (2.36): Arch and anything newer run it, older distributions build from source.

First launch

forkstify without a catalog opens the setup: seven steps, nothing to type you do not already know, each one skippable and replayable later (:setup, or :library for the library alone).

1. The catalog — paste the url of your fork of forkstify-catalog, let gh fork it for you, or clone the reference in local mode.
2. The git identity, only if your machine has none.
3. The connection — the phone announces the device over zeroconf, the browser grants the Web API.
4. The library — liked tracks, liked albums, followed artists.
5. The playlists to count, ticked and remembered.
6. The comfort dial.
7. The coverage — generate the cards your most played artists lack.

Then home: your artists, liked first; ⏎ starts, / searches the catalog and Spotify, space shows the keys.

The catalog

One file per artist, cards/<slug>.toml:

format = 1
name = "The Cure"
mbid = "69ee3720-a7cb-4402-b48d-a02c366f2bcf"
tags = ["post-punk", "80s"]
tops = ["A Forest", "Lullaby"]
links = [
  { to = "siouxsie-and-the-banshees", type = "member", note = "Robert Smith, 1982–84" },
  { to = "joy-division", type = "scene" },
]

Everything but format, name and mbid is optional. Link types are a closed list — member, collab, similar, family, scene, influence — each with a proximity the engine reads. The reference catalog's CONTRIBUTING says how a proposal is made and read.

Configuration

~/.config/forkstify/config.toml, written with its defaults on the first run: the catalog's path, the comfort to open with, and a [tuning] section with every number the engine reasons with — what a like weighs, how long a track steps back after playing, how far the adventurous branch may leap. Each one is explained in docs/tuning.md.

The documentation

Everything in this repository is in English, prose included (0024), and the documents are the project's memory: docs/vision.md for what it is, docs/decisions/ for every decision taken (one file each, dated, never rewritten), docs/design/ for the living notes by subject, docs/progress.md for where things stand. What each version brings is in CHANGELOG.md — that one is for whoever uses forkstify, not for whoever builds it.

Contributing

Open an issue, not a pull request. forkstify is issue-first: a contribution arrives as a well-described issue, a maintainer triages it, and the change is implemented — by an agent, most of the time — and reviewed by a human before it lands. Writing code stopped being the bottleneck; knowing precisely what to write never did, so that is the half being asked for. Prepare the issue with your own agent if you like — precision is the contribution. Pull requests from outside the maintainers are closed automatically, with a pointer to CONTRIBUTING.md, which says why and what a usable issue holds.

The catalog is the exception: artists, links, tags and tops live in forkstify-catalog, and that repository takes pull requests — a card is data you can read in full, and there the review is the pull request (0025).

License

MIT — see LICENSE. The catalog's own license is decided in its repository.