@schilderlabs/pitown

Globally installable CLI for Pi Town

Package details

← Back
package

Install @schilderlabs/pitown from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@schilderlabs/pitown
Package
@schilderlabs/pitown
Version
0.2.7
Published
Mar 16, 2026
Downloads
42/mo · 6/wk
Author
robschilderr
License
MIT
Types
package
Size
295.3 KB
Dependencies
2 dependencies · 0 peers

Security note

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

README

@schilderlabs/pitown

The installable Pi Town CLI.

Pi Town is an experimental orchestration tool for Pi.

Credits

Pi Town is built on top of Pi. Credit to Mario Zechner and the Pi project for the underlying coding agent runtime Pi Town orchestrates.

Pi Town was also inspired by Gastown. Credit to Steve Yegge for pushing on multi-agent orchestration ideas that made this project worth exploring.

For the full project overview, roadmap, and architecture context, see the main repo:

Install

npm install -g @schilderlabs/pitown
npm install -g @mariozechner/pi-coding-agent

pitown run requires Pi to be installed and authenticated. Verify Pi first:

pitown doctor
pi -p "hello"

Usage

pitown --help
pitown
pitown mayor
pitown mayor "plan the next milestones"
pitown run --repo /path/to/repo --plan /path/to/private/plans --goal "continue from current scaffold state"
pitown status

If you are already inside a repo, pitown and pitown mayor use the current working repo by default.

The main workflow is:

  1. cd into a repo
  2. run pitown or pitown mayor
  3. use /plan inside the mayor session when you want a read-only plan first
  4. use pitown board, pitown peek mayor, or pitown msg mayor "..." as needed

Inside the mayor session:

  • /plan toggles read-only planning mode
  • /todos shows the captured numbered plan
  • leaving /plan returns the mayor to normal execution and delegation mode

Runtime storage

By default, Pi Town stores local runtime state under ~/.pi-town and keeps private plans outside the target repo.