torusv0.24.0docs

A multi-agent harness for the terminal

install
$ pi install git:github.com/tankdonut/torus@v0.24.0

MIT, free software including at work. Runs on any provider the pinned pi engine speaks; bring your own keys.

Source and releasesdocs index

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 │ 1242 │ SessionEndReason (type)                              │ "quit" | "reload" | "new" | "resume" | "fork" — pi's                 │
 │      │                                                      │ session_shutdown reasons.                                            │
 ├──────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────┤
 │ 1257 │ registryShutdown(reason?): Promise<void>             │ Session-shutdown cleanup: kill panes, clear toast timers, stop       │
 │      │                                                      │ controls; replacement reasons also retire in-memory records.         │
 └──────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────┘

 <results>
 <files>
 - /home/user/torus/extensions/fsutil.ts - shared filesystem/formatting/timing helpers; 20
 exported symbols listed above
 - /home/user/torus/extensions/registry.ts - delegation registry; 58 exported symbols (types,
 functions, constants) listed above
 </files>

 <answer>
 Complete export inventories for both files with one-line summaries per symbol, derived from full reads of both files plus their doc
 comments. fsutil.ts is the state/filesystem foundation (project keys, state/scratch dirs, JSON IO, pruning, caching, formatting);
 registry.ts is the delegation/fleet runtime (records, tmux panes, beacons, steering, rehydration, teams, external runs).
 </answer>

 <next_steps>
 Ready to proceed — no follow-up needed. If you want cross-references (who imports each symbol), say which symbol and I can grep usage
 sites.
 </next_steps>
 </results>

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
torus fleet · explorer glm-5.3-flash ✓ done 8t · 29.2k→3.9k · $0.0109 · 50s · j/k scroll · g/G ends · [esc] back · 01a1d241-3385-769d-a…
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 │ RECORD_TEXT_CAP                                 │ const       │ 4000-char bounded head of final text kept on finished/rehydrated   │
 │                                                 │             │ records.                                                           │
 ├─────────────────────────────────────────────────┼─────────────┼────────────────────────────────────────────────────────────────────┤
 │ parseLastTurnText(raw)                          │ function    │ Extract the last turn block from a raw log, undoing the two-space  │
 │                                                 │             │ child indent and stripping markers.                                │
 ├─────────────────────────────────────────────────┼─────────────┼────────────────────────────────────────────────────────────────────┤
 │ readFullRecordText(record)                      │ function    │ A record's complete final text read back from its log; null when   │
 │                                                 │             │ unreadable.                                                        │
 ├─────────────────────────────────────────────────┼─────────────┼────────────────────────────────────────────────────────────────────┤
 │ rehydrateFromLogs(currentSessionId?)            │ function    │ Rebuild registry records from the project's delegation logs after  │
 │                                                 │             │ a resume (capped at 50, skips live foreign beacons).               │
 ├─────────────────────────────────────────────────┼─────────────┼────────────────────────────────────────────────────────────────────┤
 │ SessionEndReason                                │ type        │ "quit" | "reload" | "new" | "resume" | "fork" — pi                 │
 │                                                 │             │ session-shutdown reasons.                                          │
 ├─────────────────────────────────────────────────┼─────────────┼────────────────────────────────────────────────────────────────────┤
 │ registryShutdown(reason)                        │ async       │ Session-shutdown cleanup: kill panes, drop toasts/controls; clears │
 │                                                 │ function    │ records for replacement reasons.                                   │
 └─────────────────────────────────────────────────┴─────────────┴────────────────────────────────────────────────────────────────────┘

 </answer>

 <next_steps>
 Both files are shared modules imported by the extension set (`registry.ts` imports `fsutil.js` directly). If you need per-symbol call
 sites, grep for the symbol name across `extensions/` — most consumers are the delegation, fleet, roster, and memory extensions.
 </next_steps>
 </results>

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
torus fleet · explorer glm-5.3-flash ✓ done 6t · 31.0k→3.2k · $0.0090 · 38s · j/k scroll · g/G ends · [esc] back · 01a1d240-5902-748e-9…
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
The fleet browser over a live run: the task the explorer was given, its transcript as it works, and the steer/stop footer under it. A capture of a real session, regenerated by npm run -w site capture.

torus runs on the pinned, stock pi engine. A lead session hands work to a roster of specialist agents, and the terminal shows every one of them running: live transcripts, live tokens, mid-run steering.

extensions
33 extensions
tools
35 tools
agents
8 agents
skills
14 skills
release
v0.24.0 release

Hand the work to a roster

Every specialist is one slash dispatch away: /builder,/critic, /explorer, /librarian, /looker,/reviewer, /dreamer. Sessions delegate into parallel fan-outs and sequential pipelines, and every agent also runs as a persona of the main session (alt+p cycles them). Persistent teams take delegation further: named members hold mailboxes and a shared tasklist, survive restarts, and answer to the same fleet browser as any other run.

 gh/git/curl via bash) [chain=fast -> opencode-go/glm-5.3-flash]
 looker: Vision specialist: answers questions about screenshots, diagrams, and UI captures (image-capable flash model). Dispatch
 whenever a question depends on seeing an image. [chain=fast -> opencode-go/glm-5.3-flash]
 reviewer: Practical adversarial reviewer: plans, docs, code, work descriptions; blocker-finder, not perfectionist [chain=primary ->
 opencode-go/glm-5.3-flash]
 concurrency caps (max parallel runs per model, provider account-level): opencode-go/glm-5.3-flash=uncapped

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Update Available
 New version 1.5.2 is available. Run pi update
 Changelog: https://pi.dev/changelog
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

torus · leader · glm-5.3-flash · high · zai|opencode-go · perm:default · mcp:2 · sbx:off
 gh/git/curl via bash) [chain=fast -> opencode-go/glm-5.3-flash]
 looker: Vision specialist: answers questions about screenshots, diagrams, and UI captures (image-capable flash model). Dispatch
 whenever a question depends on seeing an image. [chain=fast -> opencode-go/glm-5.3-flash]
 reviewer: Practical adversarial reviewer: plans, docs, code, work descriptions; blocker-finder, not perfectionist [chain=primary ->
 opencode-go/glm-5.3-flash]
 concurrency caps (max parallel runs per model, provider account-level): opencode-go/glm-5.3-flash=uncapped

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Update Available
 New version 1.5.2 is available. Run pi update
 Changelog: https://pi.dev/changelog
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
The roster as the session sees it: agent descriptions, model chains, and per-provider concurrency caps.
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
torus fleet · ↑↓ move · enter/click open · x stop (y/n) · [esc] close
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
❯ ⠏ @index (librarian) ⧉docs-catalog glm-5.3-flash t1 · 0→0 · 5s
  ⠏ @scout (builder) ⧉docs-catalog glm-5.3-flash t1 · 0→0 · 5s
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
torus fleet · ↑↓ move · enter/click open · x stop (y/n) · [esc] close
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
❯ ⠦ @index (librarian) ⧉docs-catalog glm-5.3-flash t2 · 0→0 · 6s
  ⠦ @scout (builder) ⧉docs-catalog glm-5.3-flash t2 · 0→0 · 6s
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
A two-member team in the fleet browser: @handles with their agents, models, and live turns.

The fleet browser

Every running agent appears in the statusline fleet strip with live turns and tokens. alt+t opens the fleet browser over everything running: presss to steer an agent with a message, x to stop it.

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Update Available
 New version 1.5.2 is available. Run pi update
 Changelog: https://pi.dev/changelog
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

torus · leader · glm-5.3-flash · high · zai|opencode-go · perm:default · mcp:2 · cost:+$0.0039 · sbx:off
fleet 1 · 1 ⠼ explorer 13s · alt+t all

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
~/torus (main)
0.0%/1.0M (auto)                                                                                      (opencode-go) glm-5.3-flash • high
 reviewer: Practical adversarial reviewer: plans, docs, code, work descriptions; blocker-finder, not perfectionist [chain=primary ->
 opencode-go/glm-5.3-flash]
 concurrency caps (max parallel runs per model, provider account-level): opencode-go/glm-5.3-flash=uncapped

▶ explorer delegated · use grep to list every exported symbol in extensions/fsutil.ts with a…

torus · leader · glm-5.3-flash · high · zai|opencode-go · perm:default · mcp:2 · cost:+$0.0044 · sbx:off
fleet 1 · 1 ⠏ explorer 13s · alt+t all

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
~/torus (main)
0.0%/1.0M (auto)                                                                                      (opencode-go) glm-5.3-flash • high
A delegation in flight: the fleet strip carries the running agent; the statusline carries the session.
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
torus fleet · ↑↓ move · enter/click open · x stop (y/n) · [esc] close
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
❯ ⠴ explorer glm-5.3-flash t6 · 25.9k→491 · $0.0069 · 16s
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
torus fleet · ↑↓ move · enter/click open · x stop (y/n) · [esc] close
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
❯ ⠴ explorer glm-5.3-flash t5 · 25.4k→718 · $0.0060 · 15s
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
The fleet browser list over the same session. Every terminal block on this page is a capture of a real session, not a mockup.

A pin, not a fork

torus owns everything around the model calls; the engine beneath it is a stock, pinned dependency, overridable per session with TORUS_PI_BIN. Engine releases are dependency bumps, not merges.

package.json
"@earendil-works/pi-coding-agent": "1.5.2"
memory
Git-backed notes injected into future sessions; /reflect distills a session into durable memory, /goal pins a standing objective.
agent skills
Skills follow the Agent Skills open standard, so the same skill runs in Claude Code and Codex unchanged; external skills drop into ~/.agents/skills/ with no configuration.
guards
Context-integrity guards watch what reaches the model, credentials are redacted in delegation logs, and memory writes pass a read-only dreamer. The threat model is on the security page.
automode
Opt-in auto-approval for unattended runs: a decision model judges each shell command, and the audit log and other guards stay on.
serve
An authenticated HTTP surface over the delegation core: POST /run starts a run, fleet-visible like any other.
worktrees
Isolated git worktrees per task, so parallel agents never share a checkout.

The numbers are the repository’s

torus is free software under the MIT licence, developed in public. The counts above and the graph below are derived from the repository at build time, not typed in by hand.

A multi-agent coding harness on the pinned stock pi engine: a lead session that delegates to a roster of specialist agents with live visibility into everything they do.

  • JavaScript 51%
  • TypeScript 33%
  • Markdown 6%
  • JSON 5%
  • Astro 2%
  • Other 2%
Licence
MIT
Latest release
v0.24.0
Commits
612
Contributors
1
Last push
2026-11-18
2026-10-04: 28 commits2026-10-05: 25 commits2026-10-06: 11 commits2026-10-07: 61 commits2026-10-08: 1 commit2026-10-09: 40 commits2026-10-10: 6 commits2026-10-11: 16 commits2026-10-12: 1 commit2026-10-13: 7 commits2026-10-14: 2 commits2026-10-15: 4 commits2026-10-16: 6 commits2026-10-17: 10 commits2026-10-18: 21 commits2026-10-19: 7 commits2026-10-20: 0 commits2026-10-21: 0 commits2026-10-22: 27 commits2026-10-23: 0 commits2026-10-24: 28 commits2026-10-25: 62 commits2026-10-26: 15 commits2026-10-27: 0 commits2026-10-28: 0 commits2026-10-29: 16 commits2026-10-30: 30 commits2026-10-31: 5 commits2026-11-01: 48 commits2026-11-02: 6 commits2026-11-03: 1 commit2026-11-04: 3 commits2026-11-05: 18 commits2026-11-06: 4 commits2026-11-07: 6 commits2026-11-08: 9 commits2026-11-09: 5 commits2026-11-10: 0 commits2026-11-11: 11 commits2026-11-12: 8 commits2026-11-13: 38 commits2026-11-14: 10 commits2026-11-15: 4 commits2026-11-16: 2 commits2026-11-17: 3 commits2026-11-18: 7 commits
612 commits since 2026-10-04. One column per day since the public history began, as tall as that day's commits.

Four install paths

As a pi package

With pi installed, one command loads the full extension pack, skills, and agent roster: no clone, no build. Launcher-only surfaces such as torus serve are not part of this mode.

package
$ pi install git:github.com/tankdonut/torus@v0.24.0

As a single binary

Download torus-<os>-<arch> from the releases page, make it executable, and run it; the first launch self-bootstraps the runtime.

binary
$ chmod +x torus-<os>-<arch> && ./torus-<os>-<arch>

In a container

The full toolchain, no host install:

docker
$ docker run --rm -it -v "$PWD:/workspace" ghcr.io/tankdonut/torus

From source

The contributor path. You need Node 22.12 or newer. tmux is optional, since delegation panes appear only inside tmux.

source
$ git clone https://github.com/tankdonut/torus.git && cd torus
$ ./make.sh npmrc
$ npm install
$ ./runtime/bin/torus.mjs

Install it, open the terminal, meet the roster. If you do not like it,pi remove is one command too.

Docs indexSecurityChangelog

Questions before you install

Anything else is best asked where the code is: open an issue.

Is torus open source?

Yes, under the MIT licence. Use it anywhere, including at work. The engine beneath it is a pinned dependency, not a fork: the harness and the engine are both readable, each in its own repository.

Does it replace pi?

No. pi is the engine; torus is the harness around it. The engine stays a stock pin in package.json, overridable per session with TORUS_PI_BIN, so engine releases are dependency bumps rather than merges.

What do I need to run it?

From source: Node 22.12 or newer. The binary and container installs carry their own runtime. tmux is optional; delegation panes appear only inside it.

Which models does it use?

Any provider the pi engine speaks. Each roster agent carries its own model chain with per-model concurrency caps, so cheap tiers run lookups while the primary chain handles builds. Bring your own keys.

What does a delegated agent see?

Its task text, its tools, and nothing of the lead conversation. Credentials are redacted in delegation logs, and memory writes pass through a read-only dreamer.

Can I steer a running agent?

Yes. alt+t opens the fleet browser over every live run: s steers one mid-run with a message, x stops it, and the transcripts are on screen the whole time.

Can I leave a session running unattended?

Opt in with --permission-mode auto. The automode decision model judges every shell command against your rules, risky commands stop for a dialog (or block when headless), and each decision lands in an audit log. The other guards stay on.

How do I get my work back out?

Plain git branches and commits. Teams, mailboxes, and state live under ~/.torus as ordinary files; nothing is stored in a proprietary format.