Toilet-Pi

Control your pi sessions from a browser or CLI.

Toilet-Pi gives you one mobile-friendly view of pi sessions across your computers. You can watch active work, send prompts, abort a run, resume an inactive session in the background, or start a new session in a project.

How it works

Browser
   │
   ▼
Central Toilet-Pi server
   ▲                 ▲
   │                 │
Host supervisor      Shared extension
(one per machine)    (one per running session)
   │
   └── starts matching pi or OMP background sessions on demand

The central server is a lightweight WebSocket hub: it keeps a live overview of connected machines and routes browser commands and session events. Each machine runs a supervisor that discovers local pi and OMP session files and launches the matching runtime. Normal interactive sessions connect directly through the shared Toilet-Pi extension.

This design provides one UI across multiple computers without moving session files or model credentials to the server. Connections are outbound from each machine, interactive sessions remain independent when Toilet-Pi is unavailable, and server state can be rebuilt as machines and sessions reconnect.

What you get

• Live access to normal interactive pi sessions
• Sessions grouped by machine or project
• Remote prompts and aborts
• Background resume for inactive sessions
• New background sessions from the browser
• Seamless handoff back to the local pi TUI
• Plain-text orchestration CLI with tracked dispatch, settlement waits, and branch-aware history
• Scoped orchestrator tokens and browser model/thinking selection

Interactive sessions remain usable if Toilet-Pi is offline. Background sessions keep running and reconnect after temporary server outages; they stop when their host supervisor shuts down, the session is closed, or an interactive agent takes ownership.

Requirements

• Node.js 22.19 or newer
• A compatible coding agent: pi or OMP
• Git

Quick start

1. Install Toilet-Pi

Clone the repository, install its dependencies, and install the extension for your agent:

git clone https://github.com/mrexodia/toilet-pi.git
cd toilet-pi
npm run setup
# pi
pi install https://github.com/mrexodia/toilet-pi

# OMP
omp plugin install github:mrexodia/toilet-pi

Both agents load the same toilet-pi.ts extension; OMP does not require a separate entrypoint.

To update later, run pi update --extensions for pi or omp plugin upgrade toilet-pi for OMP, then restart the agent or run /reload.

2. Start the server

npm start

The server prints an Admin login URL. Open that URL in your browser.

By default the server runs at http://localhost:3457. Its generated admin token is stored in ~/.pi/agent/toilet-pi-server.json.

3. Connect your machine

In the web UI:

1. Open Installation.
2. Generate a machine connect URL.
3. Copy the URL.

Then open pi or OMP on that machine and run:

/toilet-pi setup wss://your-server/ws?token=...

Use the exact ws:// or wss:// URL generated by the web UI. Do not use the browser Admin login URL.

4. Start the supervisor

Keep this running on each connected machine:

npm run supervisor

The supervisor makes local pi and OMP sessions and projects visible and starts matching background processes when requested from the browser.

5. Use Toilet-Pi

Open the web UI to:

• inspect sessions across connected machines
• send a prompt to an active session
• resume an inactive session by sending it a prompt
• start a new session from the Projects view
• abort an active run

Normal local pi and OMP sessions connect automatically through toilet-pi.ts.

CLI

A compact plain-text CLI supports discovery, model/thinking selection, dispatch, lifecycle control, observation, and history:

node cli/toilet-pi.js --help

Log in once with a hidden admin-token prompt:

npx toilet-pi login --server https://toilet.example.com
npx toilet-pi hosts
npx toilet-pi logout

Login saves the server URL and session cookie—not the admin secret—in ~/.pi/agent/toilet-pi-auth.json. Treat this plaintext file as a secret; it uses owner-only permissions on Unix and inherits directory ACLs on Windows. Logout removes it locally, without revoking copied cookies. Environment credentials remain optional overrides, including scoped orchestrator tokens.

The CLI never reads/modifies machine configuration or implicitly starts a session. models returns models and their supported thinking levels in one request.

toilet-pi sessions
toilet-pi history SESSION --last 6
toilet-pi resume SESSION --timeout 90
toilet-pi send SESSION --stdin --wait
toilet-pi wait SESSION --input INPUT_ID

Tracked prompts include a visible correlation marker. wait uses agent_settled, not transient idle updates; settlement is not task success. Input IDs are printed before transmission for reconciliation, and mutations are never automatically replayed. OMP's new runtime capabilities remain unverified; unsupported operations fail conservatively.

See CLI usage and protocol and the orchestrator implementation plan.

Useful extension commands

/toilet-pi

Show the available Toilet-Pi subcommands.

/toilet-pi setup [connect-url]

Enter or replace this machine's connect URL. Omit the URL to open the setup prompt.

/toilet-pi status

Show the current Toilet-Pi connection status.

To try the extension without installing it permanently:

pi -e https://github.com/mrexodia/toilet-pi

Adding another computer

On every additional computer:

1. Clone the repository with git clone https://github.com/mrexodia/toilet-pi.git.
2. Enter the repository and run npm run setup.
3. Install the extension with pi install https://github.com/mrexodia/toilet-pi or omp plugin install github:mrexodia/toilet-pi.
4. Generate a fresh machine URL from Installation in the web UI.
5. Run /toilet-pi setup <machine-url> inside pi or OMP.
6. Start npm run supervisor.

Generate a separate machine URL for each computer.

Cloudflare Workers deployment

First generate a strong server token:

node --input-type=module -e "import { randomBytes } from 'node:crypto'; console.log(randomBytes(32).toString('base64url'))"

Then deploy the server and web UI. Paste the generated token when Wrangler asks for the secret value:

cd server
npx wrangler login
npx wrangler secret put TOILET_PI_SERVER_TOKEN
cd ..
npm run deploy

After deployment, open:

https://your-worker.workers.dev/#token=YOUR_SERVER_TOKEN

The supervisor and shared pi/OMP extension still run locally on every connected computer.

Configuration

Common environment variables:

The supervisor scans both ~/.pi/agent/sessions and ~/.omp/agent/sessions, tags each session with its source runtime, and launches the matching command when resuming it. OMP itself also calls its agent-directory variable PI_CODING_AGENT_DIR; OMP_CODING_AGENT_DIR is a Toilet-Pi supervisor alias that lets pi and OMP use distinct overrides in the same process. On Linux and macOS, the supervisor also follows OMP's active XDG_DATA_HOME/omp/sessions layout.

Machine configuration is normally stored in the active agent directory as toilet-pi.json. The supervisor checks the default runtime's directory first, then the other runtime.

Troubleshooting

• Machine not visible: make sure npm run supervisor is running on that machine.
• Interactive session not visible: confirm the package is installed with pi list or omp plugin list, then restart the agent or run /reload.
• Inactive session will not start: the machine's supervisor must be connected.
• Wrong server configured: run /toilet-pi again with a newly generated machine URL.
• Remote access fails: use HTTPS/WSS when exposing Toilet-Pi outside your local network.

Security and persistence

Treat the Admin login URL, server token, machine URLs, and orchestrator tokens as secrets. Use HTTPS for remote deployments. Prefer short-lived, host/session-restricted orchestrator grants for automation; see CLI permissions. These scopes are not an agent/tool sandbox.

Server session state is held in memory and rebuilt as clients reconnect. Your actual pi and OMP session files remain on their original machines.

License

MPL-2.0