itchio/itch: the desktop client for playing itch.io games

What the itch app is for, and what it is not

The README states the goal plainly: a desktop application you can download and run games from itch.io with, plus updates and notifications when games are updated. It also states the inverse, that the goal is not to replace the itch.io website. That sentence is the most useful thing in the repository, because it sets the boundary for every design decision below it. This is a client for the part of itch.io that involves files on your disk: fetching a build, unpacking it, recording where it went, launching it, and noticing when the developer uploads a new build.

The audience follows from that. If you browse itch.io in a browser, buy a game, and never want to think about it again, the app is optional. If you have a library of downloads, several in-progress builds from the same developer, or you want the update notification instead of checking a page manually, the desktop client is doing work the website does not do. The README does not claim any capability beyond that, and it does not describe a mobile client.

Three processes: Electron, a Go daemon, and a setup binary

The architecture diagram in the README shows three components. The itch app itself is an Electron application with a main process holding Redux state, business logic and process management, and a renderer process running a React UI whose state is synchronized from the main process through electron-redux. The README describes a reactor pattern in the main process for handling side effects triggered by Redux actions. That is a normal Electron split, and the interesting part is what the main process talks to.

butler is a separate Go daemon in its own repository. The README assigns it downloads, installs, updates and launches, a SQLite database for installation data, and TCP-based RPC back to the Electron app. It is spawned as a child process and tied to the app's lifecycle, so closing the app ends the daemon rather than leaving a background service. itch-setup is a second Go executable that handles initial installation and self-updates. Neither is bundled in this repository as source; both are fetched as binaries through a service the README calls broth, which proxies the itch.io API to provide fixed download URLs. That means the TypeScript in this repository is a coordinator, and the code that actually moves game files lives elsewhere.

How broth picks a butler version and upgrades it

The version management section is the most concrete part of the README. Binaries are hosted under https://broth.itch.zone/{package}/{platform}/{version}, with the platform formatted as {os}-{arch}, for example linux-amd64, darwin-arm64 or windows-386. Semver constraints live in src/main/broth/formulas.ts: butler is pinned to ^15.20.0 and itch-setup to ^1.8.0. The app fetches a /versions endpoint and picks the newest version satisfying the constraint. Canary builds use -head channels with no constraints and always take the latest.

The upgrade flow runs on startup. The app validates .chosen-version against an installed marker, and if the app version changed since the last run it checks for new component versions. It downloads a zip, extracts it with CRC32 verification, runs a sanity check, updates .chosen-version, and cleans up old versions. On Linux the local store is ~/.config/itch/broth/, with a butler/ directory containing versions/{version-hash}/butler, a downloads/ directory used temporarily, and the .chosen-version file, and an itch-setup/ directory with the same structure.

The sanity check is worth pausing on. It is the app admitting that a downloaded binary can be corrupt or wrong for the platform, and that the failure needs to be caught before the daemon is spawned rather than after a download mysteriously dies. The README does not say what the sanity check does, which is the kind of gap that matters when a download fails.

Installing the itch app and starting it in development mode

For players, the README does not give an installer command. It points at https://itch.io/app for downloads and at the Installing the app page of the documentation for detailed instructions, so the platform-specific install steps live outside this repository.

For developers, the README's quick start assumes Node.js and npm are already present. The first command installs dependencies; the second starts the app in development mode with a watcher that rebuilds on changes.

# Install dependencies
npm install

# Start the app in development mode (watches for changes and rebuilds)
npm start

Two more scripts from the same block are useful before committing. npm run ts-check type checks the project, and npm run compile builds assets.

Pointing the app at a locally built butler

The broth system normally downloads and manages butler for you. When you are working on butler itself, the README gives an environment variable that makes the app use a local build instead of the managed version. The variable is set inline before npm start, exactly as the README shows it:

# Use a local/development version of butler instead of the bundled one
BROTH_USE_LOCAL=butler npm start

With that set, the app should skip the broth download for butler and use the local binary instead. The README does not say where that binary is expected to live, so the resolution path is something to confirm from src/main/broth/manager.ts rather than from the documentation.

Regenerating butlerd bindings is a two-repository operation

The app talks to butler over a JSON-RPC 2.0 protocol called butlerd. The TypeScript types for every request, notification and data type live in src/common/butlerd/messages.ts, and the README states that this file is autogenerated from Go type definitions in the butler repository using a tool called generous. The generated code imports createRequest and createNotification from the @itchio/butlerd npm package, which provides the runtime for launching the daemon, connecting over TCP and exchanging messages.

To regenerate after a butler API change, the README gives one command, and it comes with a hard precondition: the butler repository must be checked out as a sibling directory at ../butler.

# Requires the butler repo checked out as a sibling directory (../butler)
npm run sync-butler

Generous runs in ts mode, parses Go structs and comment annotations such as @name, @category and @caller, and emits TypeScript interfaces, enums and request helpers. The generated messages.ts is meant to be committed.

This is a real constraint, not a footnote. A contributor who clones only this repository cannot regenerate the bindings, and a butler API change that lands without a corresponding regeneration leaves the two sides out of step. The README also notes that generous writes butler-side generated files, so the tool is shared rather than owned by the app.

Where the itch app is the wrong tool

The clearest limitation is stated by the project itself: it is a desktop application, and its downloads page is itch.io/app. The README does not describe an Android or iOS client, and it does not describe a way to install games onto a phone. Anyone searching for an itch.io app on Android is looking for something this repository does not build.

A second limit is the daemon model. butler is spawned as a child process tied to the app's lifecycle, so game operations depend on the Electron app being open. If you want a headless machine that downloads and updates a library on a schedule, this is not that tool. The README does not document a way to run butler independently of the app, and the broth version management exists to keep the app's copy current, not to expose a standalone service.

A third is the dependency on broth.itch.zone. The app does not carry butler and itch-setup inside the repository; it resolves them at runtime from a service the project operates. If that service is unreachable or a platform has no build for the pinned version, the mechanism described in the README has nothing to fall back on. The README does not document an offline installation path for the components.

How this differs from a plain download from the website

The alternative most people already use is the itch.io website itself: open the game page, click download, unpack the archive yourself, and run the executable. That approach has no daemon, no SQLite database, no broth directory, and no background version resolution. It also has no update notification, no record of which build you installed, and no launch management.

The difference in approach is where the state lives. The website keeps state on the server and leaves your disk alone. The itch app keeps a SQLite database of installation data inside butler and a .chosen-version marker for its own components, which is what lets it tell you a game was updated and offer to fetch the new build. If you install two builds of the same game by hand, nothing tracks that. If you want that tracking, you are accepting a daemon that runs while the app is open and a directory of managed binaries under ~/.config/itch/broth/ on Linux. That trade is the whole product.

Editorial conclusion

Adopt the itch app if you buy or download games from itch.io on a desktop and want installs, updates and launch handled in one place. Do not adopt it expecting an Android client, a storefront replacement, or a way to run games on a phone: the repository documents a desktop application and points downloads at itch.io/app. Before relying on it, verify that your platform has a broth build for the butler and itch-setup versions the formulas pin, and check what ~/.config/itch/broth/ contains after the first launch.

Frequently asked questions

Official sources

1. itchio/itch on GitHub
2. License: MIT
3. Project website
4. README
5. Releases