A multi-agent coding harness on the pinned stock pi engine: a lead session that delegates to a roster of specialist agents (builder, critic, explorer, librarian, reviewer, …) with live visibility into everything they do.
torus owns the harness layer: roster, delegation, ambient UI, memory. The engine beneath it is a pinned, replaceable dependency.
- Delegation & teams: hand work to any agent with
/<agent> <task>, or let the session delegate into parallel fan-outs, sequential pipelines, and persistent teams with shared tasklists that survive restarts. - Live visibility: every delegation opens a tmux pane tailing what the agent does, live statusline entries, and alt+t, a fleet browser with live transcripts. Steer (
s) or stop (x) a running agent mid-run. - Persistent memory: git-backed notes injected into future sessions;
/reflectdistills a session into durable memory, and/goalpins a standing objective. - Personas: the main session itself runs as any roster agent (alt+p to cycle); every agent is both a persona and a delegatable child.
- Open-standard skills: skills follow the Agent Skills standard, so they work in Claude Code and Codex unchanged; external skills drop into
~/.agents/skills/. - Guards by default: context-integrity guards, credential redaction in delegation logs, and a read-only dreamer for memory writes; the full threat model is SECURITY.md.
As a pi package: you need pi installed first; its README covers installation. Then one command loads the full extension pack, skills, and agent roster, with no clone and no build:
pi install git:github.com/tankdonut/torus@vX.Y.ZLauncher-only surfaces (torus serve, torus acp-agent) are not part of this mode; see docs/pi-packages.md.
As a single binary: download torus-<os>-<arch> from releases, make it executable, and run it. Node must be on your PATH; npm is not. The first launch boots offline, extracting the embedded payload and dependency tree (pinned engine included) into ~/.torus/runtime:
chmod +x torus-<os>-<arch> && ./torus-<os>-<arch>In a container (full toolchain, no host install):
docker run --rm -it -v "$PWD:/workspace" ghcr.io/tankdonut/torusFrom source (contributor path). You need Node >= 22.12. Platform support is declared per extension, so on other platforms unsupported extensions skip loading with a notice instead of failing later; see docs/extensions.md. tmux is optional, since delegation panes only appear inside tmux:
git clone https://github.com/tankdonut/torus.git && cd torus
./make.sh npmrc # one-time: writes the dev-only .npmrc (agents are blocked from writing it; it never ships)
npm install
./runtime/bin/torus.mjsAll paths need provider auth on first run: /login zai signs in to the built-in Z.ai provider (GLM models). In containers, mount credentials read-only instead; see docs/container.md.
Each release ships sha256sums.txt and per-asset attestation bundles alongside the binaries. To check a download, fetch sha256sums.txt from the same release and run, from the download's directory:
sha256sum -c --ignore-missing sha256sums.txtThe sums file covers every platform; --ignore-missing skips the binaries you did not download. With the GitHub CLI (gh) installed, verify the binary's build provenance:
gh attestation verify torus-<os>-<arch> --repo tankdonut/torusThe container image carries build provenance as well. The image's X.Y and X.Y.Z tags are immutable once pushed; pin one of those, or a digest, instead of latest.
npm is not a distribution channel: the torus name on the npm registry belongs to an unrelated, dormant project.
Open with /roster, then delegate something small and watch it in the tmux pane and the alt+t fleet view. The walkthrough lives in docs/getting-started.md.
torus starts guarded in default mode; automode adds an opt-in classifier for unattended work, and bypass disables every guard for one deliberate launch. The modes, the rules example, and the narrative live in docs/getting-started.md.
User-level configuration lives in one file, ~/.torus/config.json (config.json under TORUS_HOME when set). Every section, knob, env var, and config-adjacent file is documented in docs/configuration.md. Run torus config status to see each section's effective source, including a project-level .torus/config.json.
| Want | Read |
|---|---|
| First run to first delegation | docs/getting-started.md |
| Install as a pi package (extension pack) | docs/pi-packages.md |
| Every configuration knob and file | docs/configuration.md |
| Every tool, command, and env var | docs/extensions.md |
| The agent contract (add an agent) | docs/writing-agents.md |
| Skills import/export | docs/skills.md |
| Container usage and flags | docs/container.md |
| Harness overhead vs stock pi | docs/efficiency.md |
| Releases and versioning | docs/updating.md |
| Threat model and guards | SECURITY.md |
PRs welcome, especially new agents and skills (both drop-in). CONTRIBUTING.md covers the gate and PR mechanics; AGENTS.md has the full layout and conventions. ./make.sh check is the full gate.
torus runs an agent with file, shell, and network access on your machine. Read SECURITY.md before pointing it at untrusted repositories. MIT, see LICENSE.