Skip to main content
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

​
The data flow

  • 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.