Quickstart

Install clickwheel, index your library, and load your iPod.

This walks you from zero to a freshly-loaded iPod.

1. Install

clickwheel installs as a CLI with pipx:

pipx install clickwheel

Requires Python 3.11+ and macOS. For the optional MCP server, also run pipx inject clickwheel 'clickwheel[mcp]' — see MCP server.

2. Point it at your music

clickwheel reads its settings from ~/.clickwheel/config.yaml. Set your music directory:

music_dir: /Users/you/Music

See Configuration for every option (and the env-var overrides).

3. Index your library

clickwheel scan

scan is read-only — it reads tags and writes a local SQLite catalog. Nothing in your library is modified. Re-runs are incremental.

4. Pick what goes on the iPod

Plug in your iPod, then:

clickwheel select

An interactive checkbox picker lets you choose artists/albums for the device. Your selection is saved as a playlist you can re-sync later.

5. Sync

clickwheel diff   # preview what will change
clickwheel sync   # push it to the iPod
clickwheel eject  # safely unmount

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.

FLAC files are skipped — stock iPod firmware doesn’t play them.

Next steps

Repair metadata

Fix album artists, fetch art + year + genres.

Build playlists

Curate named playlists for the device.

Scrobble to Last.fm

Submit your iPod listens.

Drive it from Claude

Use clickwheel from the Claude app, even on your phone.