# OrbTorrent Extensions

> Extensions hook into moments in a download's life in OrbTorrent, a BitTorrent app for macOS: before it starts (and can hold it) or after it finishes. They're TypeScript, run in a sandboxed JavaScriptCore host, and reach the network, files and storage only through @orbtorrent/api.

Every page here is Markdown. All of them together are in [llms-full.txt](https://orbtorrent.com/docs/extensions/llms-full.txt).

## Start

- [Build extensions](https://orbtorrent.com/docs/extensions.md): Extensions are TypeScript hooks that check a download before it starts, and can hold it, or act on it once it finishes. How they work, and where to start.
- [Your first extension](https://orbtorrent.com/docs/extensions/getting-started.md): Build an extension that holds downloads containing Windows screensavers, test it, run it on a real download in OrbTorrent, and install it.
- [Build with a coding agent](https://orbtorrent.com/docs/extensions/coding-agents.md): Describe an extension, and a coding agent such as Claude Code, Codex or Cursor writes it, tests it and tries it on your downloads, with you deciding each step.

## Concepts

- [Hooks](https://orbtorrent.com/docs/extensions/hooks.md): When beforeStart, afterFinish and afterChecks hooks run, what they receive, how they hold a download, and the limits they run within.
- [Results](https://orbtorrent.com/docs/extensions/results.md): What a hook returns, how each status shows in OrbTorrent, how to mark the files it's about, and how to write results people understand.
- [Extension settings](https://orbtorrent.com/docs/extensions/settings.md): Give an extension settings that OrbTorrent draws, such as an API key kept in the Keychain, read them with getPreferenceValues, and check them with verify.
- [Network requests](https://orbtorrent.com/docs/extensions/network.md): Reach a web service from an extension with fetch, list the hosts it needs, and handle errors, rate limits and redirects.
- [Read and add files](https://orbtorrent.com/docs/extensions/files.md): Fingerprint and upload a finished download's files, and add files such as subtitles next to them with files.save.
- [Storage and progress](https://orbtorrent.com/docs/extensions/storage.md): Keep data between runs with storage, show progress on long checks, read about the extension with environment, and wait without using CPU time.

## Workflow

- [Testing](https://orbtorrent.com/docs/extensions/testing.md): Write JSON tests that run an extension's hooks without OrbTorrent, with the network mocked, file fingerprints and storage set up, and time on a virtual clock.
- [Run and debug](https://orbtorrent.com/docs/extensions/debugging.md): Load an extension into OrbTorrent while you work on it, run a hook on a real download, read its logs, and fix what orb doctor finds.
- [Share and install](https://orbtorrent.com/docs/extensions/sharing.md): Install your extension, package it as an .orbext file anyone can install, release updates, and list it or propose it as an official extension.
- [Security model](https://orbtorrent.com/docs/extensions/security.md): How OrbTorrent runs extensions in a sandbox, what each one can and can't reach, how it keeps secrets, and how the development connection is protected.
- [Examples](https://orbtorrent.com/docs/extensions/examples.md): The templates and official extensions to learn from, a worked example that adds subtitles, and ideas for extensions to build.

## Reference

- [API reference](https://orbtorrent.com/docs/extensions/reference/api.md): Everything @orbtorrent/api provides, with each function's signature, types, limits and errors, and the JavaScript environment extensions run in.
- [The orb command](https://orbtorrent.com/docs/extensions/reference/cli.md): Every orb command and option, what it needs, what it prints, and the JSON it prints with --json, for scripts and coding agents.
- [Manifest](https://orbtorrent.com/docs/extensions/reference/manifest.md): Every field of an extension's package.json, OrbTorrent's rules for each, and what users see from it.
- [Test files](https://orbtorrent.com/docs/extensions/reference/tests.md): Every field of an orb test file, and every expectation it can check.
- [Limits](https://orbtorrent.com/docs/extensions/reference/limits.md): Every limit OrbTorrent puts on an extension, in one place, from time and memory to request sizes and result lengths.
- [Errors and fixes](https://orbtorrent.com/docs/extensions/reference/errors.md): The error messages orb and OrbTorrent give when building, testing, running and installing an extension, what each means, and how to fix it.
- [Changelog](https://orbtorrent.com/docs/extensions/reference/changelog.md): What's changed in each version of @orbtorrent/api, the extension API and the orb command, and which OrbTorrent each needs.

## For coding agents

- [AGENTS.md](https://github.com/orbtorrent/OrbTorrent/blob/main/sdk/templates/_shared/AGENTS.md): the whole API, the rules and the loop, in one file. Every extension made with `orb create` has it.
- [Agent Skill](https://orbtorrent.com/.well-known/agent-skills/index.json): for Claude Code, Codex, Cursor and other agents that use the Agent Skills format, also [on GitHub](https://github.com/orbtorrent/OrbTorrent/tree/main/skills/build-orbtorrent-extension).