@orbtorrent/api

Build extensions for OrbTorrent, the BitTorrent app for macOS. This package is the API extensions use, and orb, the command-line tool that makes, tests, builds and shares them.

An extension hooks into a moment in a download's life, like a check on a pull request: it can look at a download before it starts and hold it until the user decides, or act on it after it finishes. Its result shows in the download's Checks tab. OrbTorrent's own Fake Download Check and VirusTotal Scan are extensions built with this package.

Make one

You need Node.js 22.13 or later, and OrbTorrent to load it into.

npm create @orbtorrent/extension@latest size-guard
cd size-guard
npm install

There are two templates. before-start, the default, holds downloads bigger than a size you choose. after-finish sends a notification to your phone when a download finishes; choose it with -- --template after-finish.

The new folder has:

size-guard/
├── package.json     the manifest: hooks, permissions, settings
├── src/check.ts     the hook, named after it
├── tests/           JSON tests that run without OrbTorrent
├── assets/icon.png
├── AGENTS.md        everything in one file, for coding agents
└── README.md, CHANGELOG.md, tsconfig.json

The loop

npm test                               # orb test: runs tests/*.json without OrbTorrent
npm run build                          # orb build: validates, type-checks and bundles into dist/
npm run lint                           # orb lint: ESLint with OrbTorrent's rules
npx orb doctor                         # checks Node.js and OrbTorrent, and says what's missing
npm run dev                            # orb dev: loads it into OrbTorrent, rebuilds on every save
npx orb downloads                      # lists your downloads
npx orb run check --download "Name"    # runs a hook on one of them
npx orb install                        # asks OrbTorrent to install it, once you confirm
npx orb package                        # makes size-guard.orbext, to install on any Mac

orb dev and orb run need OrbTorrent open with Allow development extensions on, on the Develop tab of its Extensions page, and OrbTorrent asks before loading a folder the first time. Every command takes --json for output a script or coding agent can read, never prompts, and exits with 1 when something's wrong.

With a coding agent

Coding agents such as Claude Code, Codex, Cursor and Gemini CLI can build an extension for you. On OrbTorrent's Develop tab, Build an Extension → With AI turns what you want into a request to paste into your agent. Every new extension has an AGENTS.md that tells the agent the rest, and orb doctor tells it what's missing. Three steps stay with you: turning on development extensions, allowing the folder, and confirming the install.

A hook

import { Download, Result } from "@orbtorrent/api";

export default async function check(download: Download): Promise<Result> {
  const program = download.files.find((file) => file.path.endsWith(".exe"));
  if (program) {
    return { status: "failed", summary: `Contains a Windows program: ${program.path}` };
  }
  return { status: "passed", summary: "No programs" };
}

A hook returns passed, warning, failed or skipped, with a one-line summary, optional details in Markdown and a link, notify: true to show the summary as a notification too, and files to mark the files it's about. Before a download starts, failed holds it. A hook that throws or runs out of time shows "Didn't finish", and a download is never blocked by a broken extension.

| | beforeStart | afterFinish | afterChecks | |---|---|---|---| | Runs | Once the file list is known, before any data downloads | Each time every wanted file has finished | Once the other checks are done: after it finishes, and when one holds it | | Can hold the download | Yes | No, it reports | No, it reports on the checks, in download.checks | | File contents | Not yet | Yes, with "files": "contents" | Once it's finished | | Adding files next to them | No | Yes, with "files": "add" | Once it's finished | | Time limit | 15 s | 6 h (2 min of CPU) | 6 h (2 min of CPU) |

What an extension can use

Extensions run in OrbTorrent's sandboxed extension host (JavaScriptCore), not Node.js or a browser. Besides the JavaScript language, timers, URL, text encoding and crypto.randomUUID(), everything goes through this package, and OrbTorrent checks each call against the permissions in package.json:

fetch(url, { method?, headers?, body? })   // HTTPS to the hosts in permissions.network; text, JSON or bytes back
files.sha256(file)                          // a finished file's fingerprint
files.formData({ field: "text", file })     // upload a file with fetch
files.save(file, ".en.srt", contents)       // add a file next to it, such as subtitles
progress({ done?, total?, message? })       // shown in the Checks tab
storage.get / set / remove / keys           // JSON, up to 1 MB, kept across runs
getPreferenceValues()                       // the extension's settings, typed
environment                                 // name, development or not, API version
sleep(milliseconds)

Settings (text fields, passwords kept in the Keychain, checkboxes and menus) are declared in package.json, and OrbTorrent draws them. Users see what an extension can do, from its hooks and permissions, before they install it.

files.save adds only subtitles, text, images and checksums, next to a file of a finished download and named after it, and never replaces a file it didn't add. Extensions can't yet change, move or delete files, change the download, reach the local network or run programs. For those, OrbTorrent can run a program of the user's own when a download finishes, which only the user can choose, in Settings.

Versions

This package's major and minor version are the extension API's. OrbTorrent runs extensions built with its major version, up to the minor version it supports: one built with 1.2 needs an OrbTorrent that supports 1.2, and OrbTorrent says so if it's too old. Additions to the API come in minor versions, anything that would break an extension waits for a new major version, and patch versions improve orb and fix bugs without changing the API. See the changelog.

Docs

• The extension docs: a tutorial, hooks, the API, the orb command, the manifest, tests, sharing and security.
• AGENTS.md, in every new extension: the whole API, the rules and the loop in one file, for coding agents. There's also an Agent Skill and the docs in one file for language models, llms-full.txt.
• Problems: issues, or [email protected].

Licence

MIT, so your extension can use any licence you like. OrbTorrent itself is GPL-3.0-or-later.