Skip to main content
This walks you from zero to a freshly-loaded iPod. It takes about five minutes, plus however long the first library scan runs.
Before you start: you need macOS, Python 3.11+, and a classic iPod with stock firmware. See Requirements for supported models and known limits.
1

Install clickwheel

clickwheel installs as a CLI with pipx:
To also drive clickwheel from Claude, see MCP server for the optional extra.
2

Point it at your music

clickwheel reads its settings from ~/.clickwheel/config.yaml. Create it and set your music directory:
See Configuration for every option and the env-var overrides.
3

Index your library

scan is read-only: it reads tags and writes a local SQLite catalog. Nothing in your library is modified, and re-runs are incremental. A first scan of a large library can take a few minutes.
4

Pick what goes on the iPod

Plug in your iPod, wait for it to mount, then:
An interactive checkbox picker lets you choose artists and albums for the device. Your selection is saved as a playlist you can re-sync later.Want everything browsable by artist instead of a curated set? See Sync to iPod, you don’t always need a named playlist.
5

Preview, sync, and eject

sync writes the iPod database and artwork directly and copies any missing tracks. It’s additive: it won’t delete tracks you didn’t ask it to.

​
Next steps

Repair metadata

Album artists, art, year, and genres.

Build playlists

Curate named collections.

Scrobble to Last.fm

Submit your iPod listens.

Drive it from Claude

From the Claude app, even your phone.