Pi Pocket

Your Pi coding agent, in your pocket.

A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable.
Runs on your own machine or directly on your phone. No cloud VM.

Website · Quick start · Feature tour · Docs

Highlights

• Durable. Every model call, tool call, and subagent is stored as it happens. Restart the server mid-run, and the work continues.
• Multiplayer. Share a live session with presence, a side chat Pi does not see, invites, and roles.
• Made for phones. Push notifications, dictation, sharing into Pi from other apps, and a home-screen app.
• PiP. An assistant that starts, follows, and reports on your other sessions, and watches GitHub for you.
• Your models. Pi's own providers, sign-ins, skills, and prompt templates, with the model chosen per session.
• Live-editable. No build step. Pi can change Pi Pocket while it runs, and you can add your own extensions.

The feature tour covers everything else, from plan mode and peek tiles to the built-in browser.

Quick start

Requires Node.js 22.19 or newer. Runs on Linux, macOS, Windows, and Android (Termux); Linux is the most tested. Sign in to a provider with Pi first (pi, then /login), or later from the app's Providers sheet.

git clone https://github.com/TannerMidd/pi-pocket.git
cd pi-pocket
npm install
npm start

The launcher asks how your devices should connect, then prints a sign-in link and a QR code. The link is the owner's key: keep it private. --rotate-token replaces it and signs out every device that used it.

While it runs: q quit · r restart server · a change access · o open in browser · s show QR code.

Updating: stop the server, back up ~/.pi-pocket, pull, run npm install, and start again. Read the release notes first: 0.21.0 upgrades the database one way, so going back needs the backup.

Other ways to run it

• Docker or Podman: docker compose up -d --build. See docs/docker.md.

• Nix: nix run github:TannerMidd/pi-pocket, or the NixOS module services.pi-pocket.enable = true; (nix/module.nix).

• Android (Termux):

  pkg update && pkg upgrade && pkg install nodejs git
  npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  pi    # /login, then quit
  git clone https://github.com/TannerMidd/pi-pocket.git
  cd pi-pocket && npm install --ignore-scripts && termux-wake-lock && npm start

  Lancet Guard may not load on Android. If it is on but fails, start with PI_POCKET_GUARD=off.

Remote access

Choose a mode in the launcher, or pass --access:

Mode	Who can connect	Notes
local	This machine	127.0.0.1; bring your own tunnel to port 8787
lan	Your local network	Plain http
cloudflare	Anyone with the link	Free https quick tunnel, no account; needs cloudflared
tailscale	Your tailnet	Tailscale address only

Other options: --port (8787), --cwd, --data (~/.pi-pocket), --host, and -y to reuse the last access choice. npm start -- --help lists them all. PI_POCKET_BROWSER and PI_POCKET_BROWSER_ARGS pick the built-in browser and its flags when Chromium or Chrome is not found by itself.

Warning

Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Pi Pocket's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. SECURITY.md says what is protected and what is not.

Documentation

• Feature tour: every feature, in full.
• Docs site: customizing Pi without code, and writing extensions.
• Engineering and code map: how Pi Pocket is built.

Development

npm run check   # type-check
npm test        # server tests with a scripted model
npm run format  # ESLint's layout fixes, then Prettier
npm run lint    # check the layout rules

web/ changes reload every open browser, and extensions reload into the running server. node test/serve.ts runs a throwaway copy to check a change on. AGENTS.md covers editing Pi Pocket safely from inside itself, and CONTRIBUTING.md how to send a change.

Limitations

• Pi Durable is experimental, and its API can change between releases. Versions are pinned in package.json.
• Only one server process can use the database at a time.
• Pi's own extensions are not supported. Pi Pocket runs its own, on Pi Durable.
• A git worktree keeps a session's files apart; it is not a sandbox.
• The built-in browser needs Chromium, Chrome, Brave, or Edge on the server. It is tested on Linux and macOS.

The full list has the details.

Credits and license

Inspired by Mario Zechner's demo of his own Pi app. Pi Pocket is an independent project, not affiliated with Earendil. The bundled fonts keep their own licenses, which are beside them in web/fonts/.

MIT. To report a security problem, see SECURITY.md.