youndie@kotlin.website:~/src$ cat kachok/README.md

kachok

compose desktop · jdk 25 · bittorrent · mcp
A BitTorrent client in Kotlin: one common engine under a Compose Desktop window, a headless command line and an MCP server. On the desktop it runs on JDK 25 with a virtual thread per peer, and the window sits in an appframe frame, in Material or in oldge-ui, chosen in its settings.

Why it exists

kachok is a BitTorrent client written to find out what a modern JDK makes of a protocol that is mostly waiting on sockets. The engine is common Kotlin — bencode, the peer wire protocol, piece selection, choking, storage, the DHT — and the I/O behind it is whatever the platform does best. On the desktop that is JDK 25: one virtual thread per peer on a blocking socket, and a pool of 16 KiB direct buffers that travel from the socket to the disk without a copy.

It is also the largest application built on two of the Compose libraries here. The window sits in an appframe frame, and its interface comes in two kits chosen on the settings screen — Material, the default, and oldge-ui in any of its skins. Many of oldge-ui's issues were filed from kachok, by a window that needed the component.

What it does

  • Downloads and seeds from a .torrent or a magnet: link, and resumes both across a restart — the resume record is an optimisation and the disk is the source of truth.
  • Finds peers four ways — trackers over HTTP and UDP, the DHT, peer exchange and local discovery — and asks a router to forward its port over UPnP or NAT-PMP.
  • Speaks the extensions a modern swarm expects: the fast extension, the extension protocol, metadata from peers so a magnet becomes a torrent, IPv6 where the tracker offers it, and encrypted connections, dialled first and fallen back from.
  • Lets you choose what arrives and when — files skipped or raised, sequential download, limits for the whole client, a cap on downloads at once, pause and re-check.
  • Stays out of the way — a tray icon, .torrent file associations, a clipboard offer when a magnet is on it, installers for macOS, Windows and Linux.

Three ways in

The window — ./gradlew :ui:run, or an installer from ./gradlew :ui:packageReleaseDistributionForCurrentOS (.dmg, .msi, .deb).

The command line — a headless client that prints one progress line a second, and a jlink image with an ahead-of-time cache that runs on a machine with no JDK:

./gradlew :cli:run --args="download ubuntu-26.04-desktop-amd64.iso.torrent --dir ~/Downloads --seed"

An agent — kachok mcp is a Model Context Protocol server on stdin and stdout. It is a third adapter on the same engine rather than a second client: every tool is a call the window makes too — add, list, wait for completion, pause, prioritise a file, set limits — and every refusal is a sentence naming the torrent, the path and what was wrong.

{
  "mcpServers": {
    "kachok": { "command": "kachok", "args": ["mcp", "--dir", "/home/you/Downloads"] }
  }
}

How fast

Same public torrent, same machine, same link, one client at a time, three minutes each, upload capped at 800 KiB/s on both:

kachok qBittorrent 5.2.1, twice
downloaded 3.31 GiB 3.51 and 3.04 GiB
rate 19.7 MiB/s 20.0 and 17.3 MiB/s

The window runs in a 64 MiB heap; the largest surfaces it holds are Skia's and are not on it.

What it does not do

  • µTP. Every connection is TCP, and 65 % of dials on a public swarm time out because the peer is behind a NAT only µTP would reach. Deferred with its reasoning, not forgotten.
  • Version 2 torrents — still an open question rather than a plan.
  • Android, iOS and the browser. The engine is written to be lifted onto them, but only the desktop is built.
  • Anything over a network it did not open. The WebSocket for clients outside the process is bound to loopback and has no authentication, by decision.