tower-do

Shared project task board + cross-session mail for the Pi coding agent

Packages

Package details

extension

Install tower-do from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:tower-do

Package: tower-do
Version: 0.8.1
Published: Oct 13, 2026
Downloads: 2,240/mo · 429/wk
Author: wweir
License: MPL-2.0
Types: extension
Size: 352.8 KB
Dependencies: 0 dependencies · 3 peers

Pi manifest JSON

{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

tower-do — Shared Project Board + Cross-Session Mail (Pi extension)

A todo-flavored Pi extension: every session in a project shares one task board, and can send messages to the other sessions working on it.

中文版说明 / Chinese README

Two features

Parallel coding agents fail at coordination, not at coding. tower-do gives every session and subagent in a project two things:

A shared todo board. Plan, claim, update, complete, and block tasks with owners and dependencies. Every session reads and writes the same board — no daemon, no database, no server, just one file per project.
Cross-session mail. Send an addressed message to another session (or broadcast to all) and read your inbox. Mail is stored on the same board, so a peer sees it whenever it next looks — and tower_do_status surfaces your unread count.

Plus a one-line above-editor widget (TowerDo 3 open · 1 msg) showing the current workload.

Three tools:

Tool	Purpose
`tower_do`	One atomic board update. `tasks` is an upsert list (create or patch); `remove` deletes explicitly. Claim with `owner` + `in_progress`, complete with `status: "completed"`, block with `status: "blocked"` + `blockedBy`. `baseRevision` rejects a stale write instead of clobbering a peer.
`tower_do_talk`	`send` an addressed message (recipient must be `all`, `tower`, a current task owner, or an identity with recent board activity; self-send rejected); `inbox` lists and acknowledges your mail.
`tower_do_status`	Shared dashboard: every open task (recency-first), completed rows as a key ledger, your messages, and the activity tail. `taskKey` returns one task's full detail. Pass its revision back as `baseRevision`.

Install

Option 1 — from npm (recommended)

pi install npm:tower-do

Option 2 — from git

pi install git:https://github.com/wweir/tower-do.git@main

Option 3 — manual copy to the global extensions dir

mkdir -p ~/.pi/agent/extensions && cp -r tower-do ~/.pi/agent/extensions/

Pi auto-discovers the extension at startup; existing sessions pick it up with /reload.

Quick tour

One session + subagents (typical). The parent plans tasks on the board and claims owners; hands subagents the board path from tower_do_status (file-as-state); they report back; the parent closes out.

Multiple sessions, one project. Both read/write the same ~/.pi/tower-do/<project>/board.jsonl. Send a message with tower_do_talk; the peer sees it in inbox (and as an unread count in its widget / status).

Upsert, not replay. A write lists only the rows it creates or changes — a key you do not mention is left alone, so a partial write can never drop a peer's task. Deleting is explicit (remove: ["key"]).

Identity resolution: as param > config identity > session name > session id. Recording work for a subagent: pass its id (e.g. as: "coder-1").

Configuration

One optional key — ~/.pi/agent/tower-do/config.json (global, applies to every project). No environment variables.

{ "identity": "team-orchestrator" }

The field and its validation rules are documented in docs/OPERATIONS.md.

How it works

One append-only JSONL file per project (~/.pi/tower-do/<project>/board.jsonl) is the single source of truth — state and communication are the same storage. Every read re-folds the log; writes carry a monotonic revision so a peer's concurrent update is rejected instead of silently clobbered. System boundary, event semantics, and read derivations: docs/ARCHITECTURE.md.

Documentation

Doc	Content
docs/PRODUCT.md	Product scope & high-level experience
docs/ARCHITECTURE.md	System boundary, event log & folding, source layout
docs/CONTRACTS.md	Task-model invariants, ownership guard, message contracts, revision gate, test gate
docs/DECISIONS.md	Why: file-as-state, upsert writes, the ownership guard, single-clock takeover
docs/OPERATIONS.md	Install, config, release flow (tag → CI → npm), troubleshooting
README.zh-CN.md	中文版说明

Quality gate: bunx tsc --noEmit plus the suites listed in docs/CONTRACTS.md, enforced in CI on every release tag.

License

MPL-2.0.