pi-pocket README

The project's README from github.com/TannerMidd/pi-pocket. As one markdown file: README.md.

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.

Release Node.js 22.19+ MIT license

Website · Quick start · Features · Remote access

Pi Pocket in the Tokyo Night theme, on a desktop and a phone. On the desktop, the session list beside a conversation where Pi has fixed a sign-in redirect loop, its edits and a passing run of 48 tests folded into a timeline. On the phone, the same session after a teammate, Alex, asks for the push: Lancet Guard waits for approval before git push.

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 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.

Features

The full tour is in docs/features.md.

Remote access

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

Mode Who can connect Notes
local This machine Listens on 127.0.0.1
lan Your local network All addresses, plain http
cloudflare Anyone with the link Free quick tunnel with https, no account needed (Cloudflare offers quick tunnels for testing and development). The address changes each time the launcher starts but stays the same across server restarts.
tailscale Your tailnet Tailscale address only, encrypted by the tailnet

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.

[!WARNING] Anyone with steering rights can make the agent run commands on this machine, as you. That reaches everything you can: your files, Pi Pocket's own settings and sign-in tokens, and its code. A single-session invite limits what someone sees in the app, not what Pi can reach, and Lancet Guard approvals can come from anyone who can steer, including the person who asked. People who can steer every session can also invite others. Invite only people you would trust at your keyboard. View-only users cannot make Pi act.

Android (Termux)

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.

Configuration

Option Default Purpose
--access <mode> last choice Skip the access menu
-y Reuse the last access choice
--port 8787 Port to listen on
--cwd current folder Default folder for new sessions
--data ~/.pi-pocket Database, settings, uploads, and push keys
--host Listen on a specific address instead of choosing access
--rotate-token Issue a new owner link and sign out devices that used the old one

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.

Architecture

Path Role
bin/pi-pocket.js Entry point: checks the Node version, starts the launcher
src/launcher/ Access menu, server supervisor, Cloudflare tunnel, keys, QR code
src/server/app.ts The core: the durable harness over pocket.sqlite, the coordinator every commit goes through, connected tabs, access, and the session list
src/server/attribution.ts, workspace.ts, transcripts.ts Who Pi works for; a conversation's folder and its stored history, as people reach them
src/server/room.ts One conversation's shared live view, sent to every tab watching it
src/server/commands.ts What people ask of Pi: messages, forks, models, plan mode, goals, schedules, worktrees
src/server/collab.ts The people's side: chat, activity lines, reactions, pins, notes, take turns
src/server/http.ts, http/ Web files, JSON API, server-sent events, uploads, artifacts, invites, the Browser panel's frames and input
src/server/browser.ts, browser/ The built-in browser: one headless Chromium over the DevTools protocol, a page per conversation
src/server/projection.ts Turns committed conversation state into compact JSON for browsers
src/server/docs.ts Durable documents: sessions, chat, pins, notes, artifacts, subagents, schedules, goals, spend
src/server/schedules.ts, goals.ts, spend.ts, changes.ts, branches.ts, worktrees.ts One feature each, with its durable tasks or git calls
src/server/push.ts, alerts.ts Dependency-free Web Push (RFC 8291 and RFC 8292), and who gets which notification
src/server/extensions/ Live-reloaded extensions: system prompt, artifacts, browser, subagents, schedules, goals, plan mode, Lancet Guard, codemode
web/ The app: Preact and htm as plain ES modules

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.

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

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).

Limitations

Credits

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.

License

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

pi-pocket (TannerMidd/pi-pocket)

Searching Database…

422 ·GitHub
Pi-pocket
Что это такое?Pi Pocket — это надёжное многопользовательское веб-приложение, заточенное под мобильные устройства, для запуска сессий кодинг-агента Pi с вашего компьютера или телефона — без облачной виртуальной машины.
Я размещаю это сам или это облачный сервис?Это self-hosted решение: вы запускаете Node-лаунчер на своём компьютере или телефоне и открываете доступ через локальную сеть, LAN, быстрый туннель Cloudflare или Tailscale — без подключения к облачной виртуальной машине.
Как его запустить?Установите Node.js 22.19+, сначала войдите у провайдера через Pi (pi, затем /login), затем запустите лаунчер: он спросит, как устройства будут подключаться, и выведет адрес, ссылку для входа и QR-код.
Кодинг-агент Pi уже должен быть настроен?Да, Pi Pocket — это фронтенд для Pi: он использует собственный рантайм моделей Pi, выполненные входы, скиллы и шаблоны промптов, так что вы выбираете модель и провайдера для каждой сессии, а не настраиваете новый бэкенд.
Какой главный подводный камень, прежде чем на это полагаться?С базой данных одновременно может работать только один серверный процесс, Pi Durable пока экспериментальный, и его API может меняться между релизами, а поддержка Windows ещё не проверена, хотя лаунчер там запускается.
А на телефоне оно правда работает?Да, оно сделано как PWA для главного экрана: на Android откройте ссылку в Chrome, выберите «Добавить на главный экран» и запустите termux-wake-lock, чтобы Termux продолжал работать в фоне.
Сколько человек сможет сделать, если я приглашу его в сессию?Любой, кому даны права на steering, может заставить агента выполнять команды на вашем компьютере от вашего имени — с доступом к вашим файлам, настройкам Pi Pocket и его токенам; ограничения есть только у приглашений с правом просмотра — они не могут заставлять Pi действовать.
Что такое PiP?PiP («Pi in Pocket»), открывается по Alt+A, — это всплывающая панель ассистента, в которой можно видеть список ваших других сессий, читать их, запускать, писать им, следить за их запусками, а также наблюдать за репозиторием или PR на GitHub и реагировать на вебхуки.
Что делает Codemode?Включён по умолчанию: Codemode заставляет Pi писать короткие скрипты, которые вызывают его инструменты, вместо того чтобы вызывать их по одному, — при этом каждый вызов проходит те же проверки подтверждения.
Что такое Lancet Guard?Необязательное расширение (по умолчанию выключено), из-за которого рискованные вызовы bash, write и edit ждут одобрения кем-то в сессии; ему нужен ONNX Runtime, который может не загрузиться на Android.
Зачем туда включены темы Omarchy?Интерфейс повторяет каждую тему рабочего стола Omarchy (или в реальном времени следует теме вашей ОС), с тайловыми окнами в стиле Hyprland и лаунчером в стиле Walker, поэтому внешне он сочетается с настройкой Omarchy Linux, рядом с которой и создавался.
What are similar projects?herdr-web-ui, 1code, pi-harness, foreman, bivor, learn, Choruz, fleetbase
Which topics is it in?pi-agent, push-notifications, omarchy, pi, git-worktrees, pi-coding-agent, multiplayer, scheduler, qr-code, webhooks, pwa, notifications
Creator
TannerMidd
Size
8.3 MB
Stars
422
Updated
CommitOct 12Releasev0.13.2Oct 12
Age
13d
Commits · 90 Days