TannerMidd/pi-pocket

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 · Features · Remote access

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 the address, a sign-in link, and a QR code. Open the link once per browser; the cookie lasts a year. The link is the owner's key, so keep it private. --rotate-token replaces it and signs out every device that used the old link; people you invited stay signed in until you remove them under Menu → People.

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

• Durable. Every model call, tool call, and subagent is stored as it happens. Restart the server mid-run and the work continues; a cut-off tool call reruns only if that is safe.
• Multiplayer. Share a live session: presence, a side chat Pi does not see, @mentions, pins, reactions, shared notes, and take turns.
• Steer or queue. Redirect Pi while it works, queue follow-ups, or stop it.
• PiP, your assistant. Alt+A opens "Pi in Pocket" over any screen: it lists, reads, starts, and messages your other sessions, follows their runs, and tells you what came of them. What sessions and GitHub say reaches it as data, never as instructions.
• Watches and webhooks. Tell PiP to watch a GitHub repository ("when CI fails on main, fix it and tell me"), or watch a pull request from a session until it merges; webhooks bring other services' posts to Pi. Only the repository's own people count, unless you say anyone.
• Memory. Lessons Pi keeps across sessions, per project or everywhere. Pi proposes them; the owner approves what it saw.
• Dictation. Speak into the message box, or PiP's, with the browser's own speech recognition.
• Forks. Fork from any reply, edit a message and send it again, or retry it with another model. Each fork is a session of its own, optionally in a git worktree of its own.
• Works while you're away. Schedule messages to Pi (/schedule every weekday 8:00 summarize CI), and /until npm test keeps Pi going until the check passes.
• Plan mode. Pi reads and proposes a plan; nothing changes until someone approves it.
• Any provider, any model. Uses Pi's own model runtime and sign-ins, skills, and prompt templates, with the model and thinking level chosen per session.
• Omarchy themes. Every Omarchy theme, or follow your desktop's live; tiled Hyprland-style windows, a Walker-style launcher (Ctrl/⌘+K) with live theme previews, and Hyprland's motion.
• Peek tiles. One click (or Alt+P) shows your other sessions working beside the one you are in: approve their calls from there, and swap between them with a click. Only the tiles on screen stay live, so a long list scrolls cheaply.
• Built for phones. Streaming answers, Pi's tool calls folded into a timeline with diffs and live output, push notifications you can allow or deny from, sharing into Pi from other apps, and a home-screen app.
• Files and review. The Files tile (Alt+E) shows the session's folder beside the conversation, and Changes reviews every uncommitted change: word-level diffs, split or unified, and files you mark viewed. Code in Pi's replies is colored, and an HTML block previews inline, running on a tap in a sandbox.
• Branches. The git branch shows in the top bar, under the session's title, and follows any switch; tap it to switch to another branch, follow a remote one, or make a new one.
• A built-in browser. Pi opens, reads, clicks through, and screenshots pages in a real Chromium on the server, and you watch and use the same page in the Browser panel, from a phone too: your dev server on localhost included.
• Artifacts and subagents. Sandboxed HTML, Markdown, and SVG artifacts, and background subagents you can open and talk to.
• Codemode. On by default: Pi writes short scripts that call its tools, and every call still goes through the same checks.
• Lancet Guard. Off by default; turn it on in Menu → Extensions. With the specpi-lancet-guard Pi package installed and on, risky bash, write, and edit calls wait for someone in the session to approve.
• Roles, invites, and limits. Steer or view-only access, to every session or just one, through one-time links and QR codes, with spend limits per person and per session.
• Live-editable. No build step: edit the web app or an extension and it reloads in place. Add your own extensions in ~/.pi-pocket/extensions/.

The full tour is in docs/features.md.

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

Cloudflare mode needs cloudflared. On Linux the launcher can download the official release into ~/.pi-pocket/bin. To use another tunnel (ngrok, tailscale serve), choose local and point the tunnel at port 8787.

pkg update && pkg upgrade
pkg install nodejs git
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi                      # /login, then quit
# copy or clone pi-pocket to the phone, then:
cd pi-pocket && npm install --ignore-scripts && npm start

Open the link in Chrome and choose Add to Home screen. Run termux-wake-lock so Android does not stop Termux.

Lancet Guard needs ONNX Runtime, which may not load on Android. If the guard is on but cannot load, Pi Pocket blocks bash, write, and edit calls (the status line shows "guard failed"). Turn it off in the app (Menu → Extensions), in ~/.pi/lancet-guard.json, or by starting with PI_POCKET_GUARD=off.

Environment variables: PI_POCKET_ACCESS, PI_POCKET_DIR, PI_POCKET_HOST, PI_POCKET_PORT, PI_POCKET_GUARD=off, PI_POCKET_BROWSER (the browser to run, when Chromium or Chrome is not found by itself), and PI_POCKET_BROWSER_ARGS (extra flags for it, such as --no-sandbox where sandboxes are unavailable). Without a terminal (under systemd, for example), the launcher uses --access or the last choice.

Browsers render only committed state. Each session's Pi Durable view is coalesced and sent as small updates over server-sent events, so a device that reconnects or joins late sees exactly what everyone else sees. The engineering page explains the design; docs/map.md is a short map of the code.

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

Changes to web/ reload every open browser. Changes to src/server/extensions/ are reinstalled into the running server. Other server changes need Restart server from the menu, and running work resumes afterward. AGENTS.md covers editing Pi Pocket safely from inside itself, and node test/serve.ts runs a throwaway copy, with its own data and a scripted model, to check a change on.

Pi knows where Pi Pocket's own documentation is: docs/index.md starts it, for agents and people who change how Pi works without code (customizing), write extensions (extensions, with tested examples), or change Pi Pocket itself while it runs (self-editing).

• 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.
• Forks are separate sessions; there is no branch tree to switch between inside one session.
• Pi's own extensions are not supported: Pi Pocket runs its own extensions on Pi Durable, and drop-ins from ~/.pi-pocket/extensions/. Pi's prompt templates work as slash commands.
• A git worktree keeps a session's files apart; it is not a sandbox. Pi can still reach everything you can.
• Artifacts run in an opaque-origin sandbox, so localStorage and cookies are unavailable inside them.
• The browser needs Chromium, Chrome, Brave, or Edge on the server. Its pages live in memory: a restart opens each one again at its last address, but not what was typed into it. Each session's cookies are its own and last until the page closes. A browser installed as a snap (Ubuntu's Chromium) is used only when there is no other; it cannot open files outside your home folder. The list of servers running on the machine is Linux-only. Tested on Linux and macOS; not yet on Windows.

Inspired by Mario Zechner's demo of his own Pi app. Pi Pocket is an independent project, not affiliated with Earendil. JetBrains Mono is bundled under the SIL Open Font License.

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