Skip to main content

Documentation Index

Fetch the complete documentation index at: https://clickwheel.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

clickwheel is a Python CLI with a small set of focused modules and an optional MCP server layered on top of the same core logic.

​
The pieces

ModuleRole
cli.pyTyper command definitions — the CLI entry point and display layer.
actions.pyPure-logic functions shared by the CLI and the MCP server. No Rich/typer; errors are a typed ClickwheelError hierarchy.
db.pySQLite catalog — tracks, playlists, scrobble cache, MusicBrainz + genre caches.
library.pyMusic-file scanning via mutagen.
scrobble.pyLast.fm scrobbling (pylast).
ipod/Vendored iOpenPodv2 — reads/writes the binary iTunesDB + ArtworkDB.
mcp/Optional MCP server (gated by the [mcp] extra).

​
The data flow

your music files ──scan──▶ SQLite catalog ──select──▶ playlist
                                                          │
                                                   diff / sync
                                                          ▼
                                                   iPod (iTunesDB)
  • scan reads tags and populates SQLite. It never writes to your files.
  • select/edit build playlists in SQLite.
  • sync reads a playlist and writes the iPod database + artwork, copying missing audio.
  • fix is the one path that writes into your library — repairing metadata in place (it never moves or renames files, because Plex reads the same library).

​
Two surfaces, one core

The CLI and the MCP server are both thin adapters over actions.py:
  • CLI — a display adapter (Rich tables, spinners, interactive pickers).
  • MCP — an RPC adapter (structured tool results for Claude).
New library/iPod features land in actions.py first, then get a thin wrapper in each surface. This is why the two never drift apart. See Design for the deliberate constraints (single-tenant, Mac-as-source-of-truth) and MCP server for the Claude integration.