@punktfunk/plugin-itch
Adds the games the itch.io app installed to a Punktfunk host's library — with their cover art, launched straight from their install folder, and with the session ending when you quit the game.
Install it from the host's plugin store (Library → Game sources → Add a source), or:
punktfunk-host plugins add itch
Nothing to configure on Linux: it finds butler's database in the usual places
($XDG_CONFIG_HOME/itch, ~/.config/itch, Flatpak) and syncs from there. If yours lives somewhere
else, set the path in Library → Game sources → itch.io → Settings.
What is read
The itch app keeps its library in butler's SQLite database, butler.db, which the plugin opens
read-only. Installed games (butler's caves) are joined to their games and install locations:
| Host | Database |
|---|---|
| Linux | ~/.config/itch/db/butler.db, Flatpak ~/.var/app/io.itch.itch/config/itch/db/butler.db |
| Windows | C:\Users\<name>\AppData\Roaming\itch\db\butler.db, every profile tried |
| Setting | Meaning |
|---|---|
databasePath |
Absolute path to butler.db. Leave empty to find it automatically. |
What gets listed
Only caves whose game is classified game and whose butler verdict holds an executable this
host runs directly: a native Linux binary (64-bit preferred) or a shell script on Linux; a native
Windows binary or a batch script on Windows. Browser (html), Java (jar) and LÖVE games need the
itch app's own runtime and are skipped, as is any cave whose executable is no longer on disk.
Each title launches its own executable from its install folder, so the host owns the process and knows when the game exits. Art is the game's still cover (or its cover) from itch's CDN.
This store never had a built-in host scanner, so the kit's parity verb has no baseline here.
Windows: the itch folders
The itch app keeps its database in your profile. The manifest names its folder,
%AppData%\itch\db, by its own files: a current host opens it to the plugin when it installs,
and an older host asks for it under Library → Game sources, where Allow is all it takes.
The install location, %AppData%\itch\apps by default, is asked for the same way: the host runs
each game from there, so it needs the whole folder. Until the database is readable detect
reports absent and nothing syncs.
Commands
punktfunk-plugin-itch detect # is a readable butler.db on this host?
punktfunk-plugin-itch scan --preview # what WOULD be synced, as JSON (works with no host)
punktfunk-plugin-itch uninstall # drop the games and release the store claim
Development
bun install
bun run typecheck && bun test && bun run build
This plugin needs @punktfunk/plugin-kit 0.4.5 (the launch field). The lockfile is regenerated
once the kit is published.
The framework — store claim, sync engine, __config, CLI verbs, and the launcher-file parsers —
lives in @punktfunk/plugin-kit/library.
This package is the itch-specific part: find butler.db, read it, map caves to entries, answer the
host's launch-time ask. See design/library-scanner-plugins.md in the main repo.
Use of AI
This project uses AI for writing code.
License
MIT OR Apache-2.0.