pix-aria2

Pi tool for direct, resumable downloads through a private aria2 RPC daemon. It gives the agent short dl-* handles for controlling transfers and shows active progress in the TUI.

The extension starts aria2c only when first used, binds RPC to 127.0.0.1, authenticates it with a random per-session secret, and stops it when the Pi session shuts down.

Requirements

This package requires:

• Pi Coding Agent
• aria2c. pix finds it in this order: ~/.pi/agent/binary.json → ~/.pi/agent/bin → PATH.

On Windows, pix downloads the official aria2/aria2 release into ~/.pi/agent/bin on first use, with a visible status. On Linux and macOS, install aria2 with your package manager. For example:

# Fedora
sudo dnf install aria2

# Debian or Ubuntu
sudo apt install aria2

# macOS
brew install aria2

Tool

The download tool supports five actions:

Action	Required input	Result
add	url	Starts a transfer and returns a short dl-* handle
list	None	Lists active transfers with file name, percentage, bytes, speed, and ETA
pause	handle	Pauses a tracked transfer
resume	handle	Resumes a paused transfer and restores live progress polling
rm	handle	Removes the transfer from aria2 without deleting downloaded or partial files

add also accepts dir to override the destination directory. The current working directory is used by default.

Example calls:

download({
  action: "add",
  url: "https://example.com/archive.iso",
  dir: "/tmp/downloads",
});

download({ action: "list" });
download({ action: "pause", handle: "dl-sleek-pika-63" });
download({ action: "resume", handle: "dl-sleek-pika-63" });
download({ action: "rm", handle: "dl-sleek-pika-63" });

Supported downloads

aria2 downloads bytes and does not restrict file extensions. Current protocol support is:

Input	Support
Direct HTTP and HTTPS URLs	Yes
FTP URLs	Yes
Magnet links and BitTorrent	Basic aria2 support
ISO, archive, package, image, document, audio, and video files	Yes, when supplied as direct URLs
Interrupted partial files	Yes, through aria2 continuation files
Segmented multi-connection downloads	Yes, managed by aria2

This package does not extract media URLs from web pages. YouTube, Twitch, HLS playlists, DASH manifests, DRM media, authentication cookies, custom request headers, transcoding, and playback are outside current scope. Use yt-dlp, ffmpeg, or another dedicated tool for those workflows.

Runtime behavior

Each loaded extension instance owns one private aria2 daemon. The daemon uses:

• loopback-only RPC on a random port;
• a random 128-bit RPC secret;
• continuation enabled with --continue=true;
• overwrite and automatic file renaming disabled;
• one-second polling while downloads are active.

Tool results use compact status rows in collapsed mode and framed details when expanded. Active transfers also appear in a live widget with handle, file name, completion, transferred size, speed, and ETA.

Session limits

Download handles and daemon connection details are held in memory. They work across tool calls and pause/resume operations within the same running Pi process.

Quitting or fully restarting Pi stops the private daemon and discards handle mappings. Partial files remain on disk and can still be continued by aria2, but automatic cross-process reconnection is not implemented. Shared daemons, persistent handles, torrent file selection, per-download limits, and authenticated request configuration remain outside current scope.

Development

Run focused package checks from the repository root:

bun test packages/pix-aria2
bun run check
bun run typecheck

bun run typecheck checks the full monorepo, not only this package.

Install

pi install npm:@xynogen/pix-aria2

Standalone and opt-in. @xynogen/pix-core does not bundle it. It needs the external aria2c binary and starts a local daemon.

Full distro

This package is part of Pix. The installer sets up Pi and the full distro. See Install for the notes for each OS.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex

License

MIT. See LICENSE.