tankdonut/torus

A multi-agent coding harness on the pinned stock pi engine: a lead session that delegates to a roster of specialist agents (builder, 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.
## What you get
Delegation & teams: hand work to any agent with / , 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; /reflect distills a session into durable memory, and /goal pins 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.
## Quickstart
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:
sh
pi install git:github.com/tankdonut/torus@vX.Y.Z
Launcher-only surfaces (torus serve, torus acp-agent) are not part of this mode; see docs/pi-packages.md.
As a single binary: download torus- - from releases, make it executable, and run it. The first launch self-bootstraps the runtime:
sh
chmod +x torus- - && ./torus- -
In a container (full toolchain, no host install):
sh
docker run --rm -it -v "$PWD:/workspace" ghcr.io/tankdonut/torus
From 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:
sh
git clone https://github.com/tankdonut/torus.git && cd torus
./make.sh npmrc # one-time: writes .npmrc (agents are blocked from writing it by design)
npm install
./runtime/bin/torus.mjs
All 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.
## First five minutes
1. /roster: the agents, their model chains, and credentialed providers.
2. Delegate something small: /explorer where does the roster load from? Watch the right-hand pane, then alt+t for the live transcript.
3. Say team in a message (or deepwork, blueprint). Keyword gates switch the session's execution mode.
4. /goal to pin a standing objective; /reflect to distill the session into memory.
## Permission modes
torus starts in default mode: guards, sandboxing, and approval prompts judge tool calls as they run. Automode is an opt-in permission layer for unattended work: a decision model classifies each bash command, approves the safe ones, and asks before anything risky. Turn it on with torus --permission-mode auto or TORUSPERMISSIONMODE=auto, or default it on with "permissionMode": "auto" in ~/.torus/config.json; 1 and on also select auto mode, while unset, 0, off, and default keep the built-in gate. The config key sets the default, the env var overrides it, and the flag sets the env var for one session. /automode reports the live status (naming where the mode came from) and switches the current session.