npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

toilet-pi

v2.0.0

Published

Remote control pi sessions from a central web UI

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

mrexodiamrexodia

Keywords

pipi-packageomp-extensionwebsocketremote-controldaemon

Readme

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:

| Variable | Purpose | | --- | --- | | PORT | Local server port; defaults to 3457 | | TOILET_PI_PUBLIC_URL | Public URL override for the Node server | | TOILET_PI_SERVER_TOKEN | Fixed admin token instead of the generated local token | | TOILET_PI_HOST_ID | Custom name for a machine | | TOILET_PI_SESSION_DIR | Custom pi session directory | | TOILET_PI_OMP_SESSION_DIR | Custom OMP session directory | | TOILET_PI_PI_COMMAND | Path or command used to launch pi | | TOILET_PI_OMP_COMMAND | Path or command used to launch OMP | | TOILET_PI_DEFAULT_RUNTIME | Runtime for brand-new background sessions; pi by default | | TOILET_PI_SERVER_URL | Machine connect URL override | | PI_CODING_AGENT_DIR | Override pi's agent directory | | OMP_CODING_AGENT_DIR | Override OMP's agent directory for the supervisor |

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