pi-pocket 0.27.0 → 0.28.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -8
- package/docs/architecture.md +9 -1
- package/docs/customizing.md +16 -2
- package/docs/docker.md +2 -0
- package/docs/examples/quiet-note.js +21 -0
- package/docs/examples/quiet-note.ts +73 -0
- package/docs/extensions/app.md +1 -0
- package/docs/extensions/policies/api-stability.md +3 -0
- package/docs/extensions/reference/limits.md +11 -0
- package/docs/extensions/reference/pocket.md +22 -1
- package/docs/extensions/reference/theme-surface.md +12 -0
- package/docs/extensions/reference/web.md +36 -2
- package/docs/extensions.md +2 -0
- package/docs/features.md +20 -16
- package/docs/map.md +24 -12
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +3163 -0
- package/package.json +3 -2
- package/src/launcher/access.ts +75 -4
- package/src/launcher/main.ts +303 -60
- package/src/launcher/options.ts +8 -5
- package/src/launcher/serve.ts +677 -0
- package/src/server/app.ts +223 -14
- package/src/server/avatars.ts +54 -0
- package/src/server/background.ts +214 -42
- package/src/server/build.ts +53 -0
- package/src/server/commands.ts +28 -33
- package/src/server/config.ts +9 -1
- package/src/server/docs.ts +8 -1
- package/src/server/entry-presentation.ts +275 -0
- package/src/server/export.ts +26 -3
- package/src/server/extension-web.ts +113 -8
- package/src/server/extensions/pip.ts +57 -2
- package/src/server/host.ts +21 -3
- package/src/server/http/api.ts +106 -6
- package/src/server/http/assets.ts +9 -1
- package/src/server/http/conversation-routes.ts +61 -0
- package/src/server/http/events.ts +19 -0
- package/src/server/http/icon-route.ts +196 -0
- package/src/server/http.ts +41 -2
- package/src/server/icon-mask.ts +33 -0
- package/src/server/icon-render.ts +149 -0
- package/src/server/icon-store.ts +57 -0
- package/src/server/model-images.ts +124 -0
- package/src/server/pip.ts +30 -6
- package/src/server/projection.ts +127 -32
- package/src/server/room.ts +171 -8
- package/src/server/running.ts +307 -2
- package/src/server/schedules.ts +5 -0
- package/src/server/skills.ts +99 -8
- package/src/server/spend.ts +5 -0
- package/src/server/transcripts.ts +28 -3
- package/src/server/when.ts +25 -11
- package/types/pocket.d.ts +53 -2
- package/web/app-icon.js +149 -0
- package/web/app.js +12 -8
- package/web/avatar.js +46 -2
- package/web/composer.js +107 -15
- package/web/entry-presentation.js +264 -0
- package/web/extension-ui.js +18 -0
- package/web/fingerprint.d.ts +2 -0
- package/web/fingerprint.js +21 -0
- package/web/launcher.js +15 -3
- package/web/model-favorites.js +27 -0
- package/web/peeks.js +11 -3
- package/web/pip.js +7 -1
- package/web/running-board.js +1197 -0
- package/web/session-cache.js +144 -0
- package/web/session-tabs.js +58 -0
- package/web/sessions.js +51 -12
- package/web/sheets/all-artifacts.js +104 -0
- package/web/sheets/appearance.js +45 -0
- package/web/sheets/background.js +228 -0
- package/web/sheets/find.js +61 -7
- package/web/sheets/folder.js +43 -4
- package/web/sheets/menu.js +3 -1
- package/web/sheets/message.js +80 -15
- package/web/sheets/model.js +39 -3
- package/web/sheets/people.js +35 -1
- package/web/sheets/providers.js +80 -26
- package/web/sheets/schedules.js +4 -1
- package/web/sheets/shortcuts.js +1 -0
- package/web/sheets/text.js +2 -0
- package/web/sheets.js +11 -4
- package/web/store.js +837 -27
- package/web/style.css +1928 -166
- package/web/subagents-board.js +3 -2
- package/web/tab-order.js +34 -0
- package/web/theme-surface.js +7 -0
- package/web/theme.js +15 -0
- package/web/transcript.js +588 -57
- package/web/user-search.js +6 -0
- package/web/sheets/running.js +0 -130
package/docs/features.md
CHANGED
|
@@ -7,51 +7,53 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
7
7
|
- **Omarchy colors.** All of Omarchy's themes, from Tokyo Night and Gruvbox to Rosé Pine and the light ones, drawn from each theme's own `colors.toml`, in soft tiles: rounded windows and controls on 1px hairlines, soft shadows only on what floats, Geist for words and JetBrains Mono for code, paths, and numbers, with JetBrains Mono's own italic and the Nerd Fonts icons that prompts and tools print (bundled in `web/fonts/`, with Inter, Fira Code, IBM Plex Mono, and Iosevka for themes to name; `web/fonts/SOURCES.md` says where each came from); light themes too. Menu → **Appearance** (or the **Theme** tile, the launcher, or `/theme gruvbox`) picks one under **Colors**, as well as a theme folder's `colors.toml` (any Omarchy theme folder dropped into `themes/` shows there); the mini-desktop cards in Appearance preview a theme on hover or keyboard focus, and leaving without choosing restores the saved theme. The new look grows as a circle from where you tapped. **Desktop** follows the Omarchy theme of the machine Pi Pocket runs on: change your desktop's theme and the app follows within seconds, optionally with your wallpaper in the gaps.
|
|
8
8
|
- **Sheets and controls.** Sheets have a 56px title bar on wide screens, a back chevron when opened from another sheet, grouped inset lists, round toggles, and segmented settings. On phones they keep their bottom-sheet grip and drag-to-close gesture. Text sheets have Cancel and the main action together at the bottom; all existing keyboard and back flows stay available. Buttons, fields, and search share the same rounded controls across the app.
|
|
9
9
|
- **Tiled windows and motion.** On wide screens the sidebar and the session are Hyprland windows, softened: 8px gaps, rounded corners on a hairline, and a soft accent ring on the one under the mouse. Motion uses Omarchy's Hyprland curves: windows pop in at 87%, sheets and popovers rise a little as they fade in, and leave quickly, new messages slide in, and notices count down until they go. While Pi works, the conversation shows what it does; elsewhere a working session's square steps around and a small dot pulses (both hold still with reduced motion). Appearance can turn tiling off (no gaps, square corners, no ring), reduce motion (or follow the system's setting), choose Fluid motion (sheets, menus, the launcher, and notices arrive on a spring and leave quickly, over a frosted scrim; what they hold, and a tool group's first steps, follow a step apart; a message sent lifts off from the message box; each new paragraph of Pi's answer fades in, and its caret breathes; a pressed button springs back; and folding the sidebar morphs the windows into place; Width and tiling change at once, as they are set from a sheet or the launcher, which morphs skip; Auto never picks it), change the conversation's text size (13, 15, 17, or 20, or any size from 10 to 32 px typed in, in half pixels), set the width (Comfortable, which grows with a wide window, Wide, or Full: how much of the window the conversation and the message box take, per browser; phones stay as they are; a reply's code block with long lines grows past the column, centered on it, where plain text and Markdown wrap in the column, and a wide table grows toward the window's edge), set the density (Comfortable, Compact, or Tight: less room between turns, inside message cards and activity groups, between the conversation's lines, in the session list's rows, around the message box and the status line, in sheets and their lists, and in the top bar, while font sizes stay and rows on a touch screen stay a thumb tall), show Pi's thinking while it works, and show the reply speed under the message box.
|
|
10
|
-
- **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
|
|
10
|
+
- **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. Appearance → **Switch sessions with → Tabs** (off until you turn it on, in each browser) also puts the first nine of those sessions in a strip of segments above the top bar, each in its folder's color: the open one fills, one that works pulses, one that waits for you shows in the warning color, and a tap opens it (the open session takes the ninth place when it is further down the list). Choosing Tabs folds the sidebar to its rail, and Sidebar unfolds it; Ctrl/⌘+B still folds and unfolds it either way. On a phone the strip is the bars alone, and the top bar names the open session. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
|
|
11
11
|
- **Your own layout.** Appearance → **Top bar buttons**, **Status line items**, **Places**, **Message box buttons**, and **Under Pi's answers** list what shows in each place, the app's own and extensions' alike: a switch shows or hides each one, arrows move it, and **Reset** goes back to the defaults. The menu, More under an answer, Lancet Guard, and the connection's warning always show. Saved in each browser, so a phone and a desktop can differ. Extensions can arrange these too (`pocket.arrange`), and what you choose wins.
|
|
12
12
|
- **Peek tiles.** Off until you turn them on: the menu's **Peeks** tile, Alt+P, `/peek`, the launcher, or Appearance switches them on or off in one step, and so do the rail's **Peek tiles** button and the tiles button in the top bar, which shows wherever its pane is 480px wide or more (while off, it has a dot when another session waits for you). Then other sessions' live work shows beside the one you are in: one tile per session that is working, waiting for an approval, has subagents at work, finished since this browser last had it open, or is pinned, plus the one you just left. Each is a card with the session's folder square, title, and path, its last three lines (what was asked, what Pi said, its tool calls and how they went, each in two lines at most, with a mark for who or what said it), the subagents at work there, and a footer with its state in words; it changes at most once a second, and only its square moves while the session works. Its subagents at work get a line each: the state square, the name, and what it does this moment (the call it runs, the one it waits to allow, or its words), from its own peek; a tap opens it. Those waiting for an approval come first, and a tile shows three at most (the strip one), so it stays a glance however many work: **N more** opens the subagents board at the first one left out. A subagent's call waiting on its session's tile says which subagent asks, and in the column the footer says when only subagents keep the session working or waiting ("3 subagents working"). Click a tile to open its session; the one you leave takes its place, so the tiles stay put. Allow or deny a waiting call right on its tile, which shows the whole command and why the guard asks; a command that does not show whole offers Open instead of Allow, which goes to the conversation it waits in. The ✓ on a finished one marks it seen. On wide screens the tiles are a column that slides in where People and the Browser panel dock when neither is open, with **▲/▼ N need you** at its edge for waiting tiles out of view; narrower screens (and wide ones with a panel open) get a strip under the top bar that swipes sideways. Only the tiles on screen are live: once scrolling settles, the tab tells the server which, and the rest keep their last lines (their marks stay current from the session list); a tab in the background keeps none live, and with tiles off nothing is sent at all. Peeking is not being there: it does not show you in the session's people.
|
|
13
13
|
- **Launcher.** Ctrl/⌘+K (on a touch screen, the **Launcher** tile among the places, or the ⌘ button in the session search) opens a rounded search window for sessions, actions, and themes, with fuzzy matching. Search-type pills sit above grouped results with folder-color tiles, action icons, or four-color theme swatches; the selected row has a soft fill. **All**, **Sessions**, **Actions**, and **Themes** select the search type without clearing your words; `>`, `@`, and `#` still work. All starts with six recent sessions; **Show all** searches the whole session list, including archived sessions. Result counts show when a list is capped. Titles and folder or command details highlight matches, and sessions show their current, working, waiting, or archived state in a pill on the right. Arrowing onto colors shows them at once; Enter keeps them, Escape goes back. A theme that changes the look shows once chosen. Arrows, Tab/Shift+Tab, and PageUp/PageDown move the selection; Enter opens it. **Close**, Escape, a tap outside, or Back closes the launcher. Each opening starts with a fresh search and a focused input, even when it reopens during its fade-out. On a phone it is a sheet from the bottom edge, like the app's other sheets: drag it down to close it. On a touch screen it opens without the keyboard, so the results stay in sight; a tap on its search brings the keyboard up.
|
|
14
14
|
- **The menu.** The top bar's **⋯** opens a 360px popover below it on wide screens, and a bottom sheet on phones. Three columns of rounded place tiles open Files, Changes, Browser, Artifacts, Chat, Find, Launcher (on touch screens), Branch, PiP, and Peeks when available; badges show counts or news, and open places are tinted. Session actions, Subagents, and App rows have right-aligned hints and separate groups. App includes **Keyboard shortcuts** (`?`). Arrows, Home/End, and Tab move through the controls; Esc, Back, Close, or a tap outside closes the menu. Back from a sheet it opened returns to the menu.
|
|
15
15
|
- **Keyboard.** Alt+1…9 jumps to a session (hold Alt to see the numbers), Alt+↑/↓ goes to the previous or next one, Alt+N starts a new one (where Ctrl/⌘+1…9 starts it in a favorite folder), Alt+B opens or closes the browser, Alt+E the Files tile, Alt+T turns Show thinking on or off, Alt+V starts or stops dictation, and `?` lists every shortcut. On a computer, a session opens with the caret in its message box, ready to type; on a touch screen it waits for a tap, so the keyboard does not cover the conversation, and on a Mac a session opened with Alt+1…9 or Alt+↑/↓ leaves the box alone, so the next Alt shortcut still works (Option types characters in a box).
|
|
16
|
-
- **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, unless Appearance's **Keep activity folded** (off by default) keeps them on their line until you open one; a thought alone still follows Show thinking. An approval is a card at the end of its turn (the command, the reason, Deny and Allow; once answered, the call's line says who allowed or denied it), and while Pi works one line, a pulsing dot with the state in the accent (the warning color while it waits for an approval), says what it does (thinking, working, waiting for an approval, retrying) and for how long. With **Show thinking** on in Appearance (or Alt+T, or the launcher), the current thought shows above that line as it streams, and the thoughts in the conversation show their words once written (a thought alone in its group opens, and one on a timeline opens its step). A chevron before the line's dot folds the live thought away, and again brings it back. Alt+T shows a short on/off notice, even while Pi is idle. During tool calls the latest thought stays; a new response clears it until the model shares new thinking. Models that share none say so, rather than showing an old thought as current. A fold holds in that session, also over a reload, until you open it again; the setting is off until you turn it on, in each browser, and while it is off or folded the live thought is neither selected nor drawn. The reading area follows new words until you scroll up in it, and follows again for each new thought. While Pi works, **Steer**, **Queue**, or **Interrupt** beside the model chip says whether a message steers the run, waits for it to end, or stops the run at once (the tool call too, as Stop does, which also withdraws what waits in the queue) and is sent after; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; queued messages can be withdrawn, and your own, tapped open, can go back into the message box to change (**Edit**: its words above what you were typing, on a line of their own, with its files), move to Queue or Steer until Pi reads it, or go now as an Interrupt (a second tap confirms; `CONFIRM_INTERRUPT` in `web/composer.js` turns that off): that stops the run and sends only that message, while every other queued message, from everyone, stays queued in its order with its sender and mode (a restart in between loses or repeats none), and so do subagents' reports; with take turns on, moving one to Steer or Interrupt waits for your turn at the wheel, as sending does; Stop (or Esc twice) stops the run. A run stopped in the middle of a tool call ends with a "Stopped." line under its card.
|
|
16
|
+
- **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, unless Appearance's **Keep activity folded** (off by default) keeps them on their line until you open one; a thought alone still follows Show thinking. An approval is a card at the end of its turn (the command, the reason, Deny and Allow; once answered, the call's line says who allowed or denied it), and while Pi works one line, a pulsing dot with the state in the accent (the warning color while it waits for an approval), says what it does (thinking, working, waiting for an approval, retrying) and for how long. With **Show thinking** on in Appearance (or Alt+T, or the launcher), the current thought shows above that line as it streams, and the thoughts in the conversation show their words once written (a thought alone in its group opens, and one on a timeline opens its step). A chevron before the line's dot folds the live thought away, and again brings it back. Alt+T shows a short on/off notice, even while Pi is idle. During tool calls the latest thought stays; a new response clears it until the model shares new thinking. Models that share none say so, rather than showing an old thought as current. A fold holds in that session, also over a reload, until you open it again; the setting is off until you turn it on, in each browser, and while it is off or folded the live thought is neither selected nor drawn. The reading area follows new words until you scroll up in it, and follows again for each new thought. While Pi works, **Steer**, **Queue**, or **Interrupt** beside the model chip says whether a message steers the run, waits for it to end, or stops the run at once (the tool call too, as Stop does, which also withdraws what waits in the queue) and is sent after; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; Ctrl/⌘+Enter sends a message the other way while Pi works (queued when Steer is chosen, steering when Queue is) and leaves the choice as it was, and on Interrupt or with nothing running it sends as Enter does (since 0.28.0); queued messages can be withdrawn, and your own, tapped open, can go back into the message box to change (**Edit**: its words above what you were typing, on a line of their own, with its files), move to Queue or Steer until Pi reads it, or go now as an Interrupt (a second tap confirms; `CONFIRM_INTERRUPT` in `web/composer.js` turns that off), with these buttons in a quiet row at its right (since 0.28.0): that stops the run and sends only that message, while every other queued message, from everyone, stays queued in its order with its sender and mode (a restart in between loses or repeats none), and so do subagents' reports; with take turns on, moving one to Steer or Interrupt waits for your turn at the wheel, as sending does; Stop (or Esc twice) stops the run. A run stopped in the middle of a tool call ends with a "Stopped." line under its card. A session you go back to shows at once where you were in it, as this browser tab kept it, and what came while you were away rises in: at the bottom the conversation glides up to it, and scrolled up the row you read stays where it is. With Appearance's **Wait for updates** (off by default), a session that changed while you were away shows only once its updates have come (or after 2.5 seconds). Scrolled up, a round button above the end of the message box goes back down to the newest message.
|
|
17
17
|
- **Getting around on a phone, with one hand.** Back (the swipe, Android's back button, the browser's) goes back to where you were: it closes what opened last (a sheet, the menu's next sheet back to the menu, a file back to the Files tree, back to Changes when the file was opened from there, the Files tile or the Browser panel, the drawer) before it leaves the session, and leaving goes to the session before or to the list, scrolled and searched as you left it. A session opened straight away (a link, a notification) has the list under it, so back does not leave the app. What you use most is a thumb's reach from the bottom edge: the button beside the message box (or a swipe up from it) opens the places, a short sheet of big tiles (Files, Changes, Browser, Artifacts, Chat, Find, Branch, Peeks) with the session menu below them. On the conversation, swipe left for Files and right to go back; in Files, swipe right to go back. Each swipe shows a mark that lights when letting go will act. The top bar leads back to the list (counting other sessions that wait for an approval) and keeps only the buttons with something to say. Every control is a thumb's size on a touch screen (small ones, such as a code block's Copy or a reply's Pin, keep their look and take a wider tap); a tap anywhere on the message box, off its one line of text, still goes to the text; a quick second tap does not land on whatever just slid in under it; tables in replies scroll sideways instead of crushing their columns; a diff's header keeps the file's name on a line of its own on a phone; and the command a peek tile asks about opens its session when tapped. The Files tile and the browser slide in as screens of their own and slide away on back, a file slides in over the tree, and the browser's tools sit on their own row under the address. Drag a sheet down, or the drawer left, to close it. In an iPhone home screen app, which has no back gesture of its own, swipe in from the left edge to go back.
|
|
18
|
-
- **Reply to a passage.** Select words in one of Pi's replies, on a phone or a desktop, and a **Reply** button appears by the selection (below it on a touch screen, where the system's menu sits above). It puts the passage in a quote strip above the message box (tap × to drop it); the next message goes to Pi with the passage first as a Markdown quote (up to 1,500 characters), and shows in the conversation as a quote block above your words.
|
|
18
|
+
- **Reply to a passage.** Select words in one of Pi's replies, on a phone or a desktop, and a **Reply** button appears by the selection (below it on a touch screen, where the system's menu sits above). It puts the passage in a quote strip above the message box (tap × to drop it); the next message goes to Pi with the passage first as a Markdown quote (up to 1,500 characters), and shows in the conversation as a quote block above your words. **Reply to a passage** in Appearance (on by default) turns the button off in that browser.
|
|
19
19
|
- **Forks.** Tap Pi's reply → More → **Fork from here**: a new session with everything up to that reply, which then goes its own way. Tap one of your messages to **edit it and send it again**, or send any message again, to the same model or another one (a retry). Each makes a new session that forks just before the message; the original stays as it is. A fork gets its own chat (with the pins of what it inherited), a link back to where it came from, and optionally a git worktree of its own.
|
|
20
20
|
- **A new context.** Menu → **New context** (or `/reset [note]`): Pi starts fresh and no longer sees the messages so far, while everyone still does. An optional handoff note carries over what matters.
|
|
21
21
|
- **Instructions for Pi.** Menu → **Instructions for Pi** (or `/instructions …`): ground rules Pi gets with every message in this session, such as "use pnpm, not npm". Everyone in the session can see them.
|
|
22
22
|
- **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project or for everywhere: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), and everywhere's reach every session and PiP. Menu → **Memory** (its hint says how many apply here and everywhere) lists them in those two groups, each with who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, for this project or everywhere, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons and everywhere 30; past that, forget one first. Changes show as lines in the chat. Turn it off in Extensions.
|
|
23
23
|
- **A lean prompt.** A new session gets only the tools most conversations use. `browser`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools wait, and so do their prompt sections; the prompt lists them with a line each, and Pi loads one with `tool_search` when a task needs it. On a model whose provider takes tool changes in the messages (Claude 4.8 and 5, and later), the tool joins the list and stays for the conversation; on any other, Pi calls it from a `codemode` script, so the tool list and the prompt cache never change. Long guides, such as the design guide and the page-to-app messages of artifacts, are files that Pi reads when it needs them. Turn the **Tool search** module off in Menu → Extensions to offer every tool every time. A test keeps Pi Pocket's own part of a plain session's prompt at 16,000 characters (about 4,000 tokens) or less.
|
|
24
24
|
- **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, and other commands are blocked. Subagents inherit plan mode and explore under the same restrictions. **Approve plan** turns plan mode off and tells Pi to go ahead; it waits until Pi has answered since plan mode went on.
|
|
25
|
-
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or Menu → **Scheduled messages**: Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only.
|
|
25
|
+
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or Menu → **Scheduled messages**: Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only. Archiving a session that has repeating schedules says how many keep running there, with a tap to see them, and its Schedules sheet marks it as archived; nothing stops or moves (since 0.28.0).
|
|
26
26
|
- **Done when.** `/until npm test`: after each of Pi's answers, the check runs in the session's folder; while it fails, Pi gets the end of its output and keeps going, for five checks at most. A bar above the message box shows how it stands. With Lancet Guard on, the check must be a command the guard allows outright. In plan mode the check waits until the plan is approved, and past a spend limit Pi stops going on. A check cut off by a server restart is not run again, as it may have done part of its work: Pi hears so, and its next answer is checked.
|
|
27
27
|
- **Mention files.** Type `@` in the message box to pick a file or folder from the session's folder: `@` alone lists its top, `@src/` a folder's own files, and anything else matches across the whole folder (`@srvapp` finds `src/server/app.ts`). Tab or Enter (or a tap) puts the path in, and a folder opens to its files. Pi gets the message as written, `@src/server/app.ts` and all, and reads what it names; or tap **Send them along** above the box to send the files' contents with the message, as Claude Code does (text files up to 100 KB each, images as images when the model takes them). The list is git's in a repository (so ignored files stay out), and a walk that skips hidden and dependency folders elsewhere; your browser fetches it once and matches as you type, so suggestions never wait on the network.
|
|
28
28
|
- **Shell commands.** `!git status` runs in the session's folder, and Pi sees the command and what it printed with your next message, as in Pi's terminal app; `!!git status` shows it only to the people here. While it runs, a row says so, with Stop (it is in Running now too). A restart while it runs does not run it again: its entry says it was cut off. With Lancet Guard on, a command from anyone but the owner must be one the guard allows outright. A command Pi sees counts as its person's message: Pi works for them from there, as for a steer. These are a person's own commands, not Pi's: plan mode does not hold them back. Stop one from its row, or from Running now on any device.
|
|
29
|
-
- **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. In the conversation, that message shows as a card: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background
|
|
29
|
+
- **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. Tasks that end together go as one message, which joins the run in flight at its next pause rather than starting another turn (a steer, as a subagent's report is): several ending cost Pi one turn, not one each, and the answer it was writing keeps its place. A task someone stops is not told about. In the conversation, that message shows as a card each, a group for several: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background**, its row in the session list shows a terminal mark with the count, and the rail's Running now button counts the session (since 0.25.0). A tap on that count opens **Background** (Menu → **Background** opens it too, also when nothing runs): the session's commands, the newest first, and what the open one printed, as it comes. It asks again once a second while the task runs, so a dev server's log scrolls by itself; a scroll back up stops it following, and **Jump to the end** goes on. A tap on another command in the row above the log switches to it. **Stop** is there for anyone who may steer. Watching a task takes nothing from Pi: what it reads next stays where it was, so Pi still gets every line it has not read. Past the 20,000 characters the sheet keeps, or past what the log still holds, it says how many bytes it did not show. Limits: 10 running at once in a session (the owner changes it in Menu → Extensions, under Background tasks); a log past 50 MB loses its oldest segments, whole, and a command that writes more than 200 MB in a quarter of a second, or more than 500 MB in 10 seconds, is stopped at once, and Pi is told why; the last 20 ended tasks of a session stay readable. Sessions only: not subagents or PiP. Linux only (it follows processes through `/proc`); it needs bash and `split`.
|
|
30
30
|
- **Extensions' commands.** A module can add commands to the message box (`/clock-zone Europe/Berlin`), which do something without asking Pi: show a status, change a setting. They show in the suggestions with the app's own, after them; a prompt template of the same name wins. What one gives back is a notice for you alone, or a card of plain text in the conversation for everyone there, which Pi never sees and which does not change whom Pi works for; Find in session and export include it. A conversation command is for whoever may steer (whoever drives, while people take turns); a global one is the owner's, also while someone else drives; viewers get none. Each run is a durable task: sending the same text again after a lost reply gets the first run's result, a restart never runs one again, and Running now shows and stops it. See [Writing extensions](extensions/commands.md).
|
|
31
31
|
- **A person's role and the page's scroll, for extensions.** Since 0.27.0, two experimental members. `host.roleOf(personId)` gives a person's role (`owner`, `guest`, or `viewer`), or `undefined` for an id that is not a person here. It reads the role that core already uses, so a module that guards owner-only things can ask whether Pi works for the owner (`host.requesterOf` gives the id). The snapshot of `host.browser` has a `scroll` field, `{ y, viewport, height }` in CSS pixels, the same numbers that Pi's `browser` tool shows as "scrolled 0 of 800px". See [Writing extensions](extensions/host.md).
|
|
32
|
+
- **Folded inputs.** An extension can send a message the conversation shows as one line: a short label, and a summary when the message has one. Tap the line to read the message. Tap the message for its sheet, where **Show**, **Fold**, and **Hide** choose how every input of that kind shows in this browser: as a message, as the line (the usual choice), or hidden until Find jumps to it. A hidden message still starts its turn. An extension's browser code can pick one for you until you choose. The queue shows the same line. Export keeps the whole message in a folded block. Find searches the label, the summary, and the whole message, however long; Copy text copies all of it. An input the extension stored as its own kind is not a message you can send again. Peek tiles and PiP show the one line. The model still reads the whole message. Since 0.28.0.
|
|
32
33
|
- **What you sent before.** ↑ in the message box goes back through what you sent from this browser in the current session (↓ comes forward, then back to your draft), and Ctrl+R searches it. The browser keeps up to 200 entries in total across people and sessions, with duplicates removed only within your session. Old browser-wide history stays untouched, but does not appear here: it has no session IDs.
|
|
33
|
-
- **Dictation.** The mic beside Send, in the message box and in PiP's, dictates with the browser's own speech recognition, in the language the browser is set to. Words show in the box as they are heard and stay once the browser settles on them: at the caret while the box has the focus, after its text when it does not, with a space where they meet; words typed meanwhile stay too, and a phrase still being heard when you type or move the caret elsewhere finishes where it is, the next one going to the caret. It never sends by itself: tap the mic again (or Alt+V, which dictates into PiP's box while PiP is open, else into the session's) to stop, read it over, and send. Sending, leaving the session, closing PiP, or switching away from the tab stops it as well. What was heard is kept as a draft, like typing. While it listens the mic takes the accent, with a ring that breathes (still, with reduced motion), and the box says "Listening…". On a phone while Pi works, the mic takes Send's place until there is something to send. It needs a browser with the Web Speech API: Chrome, which sends the audio to Google's servers to recognise it, and Safari, on iOS too; where there is none (Firefox), the mic does not show. Browsers give a page the microphone only over https or on localhost, as Pi Pocket is served through the Cloudflare Tunnel, Tailscale, or on this device. A blocked microphone, silence, a missing microphone, or no network says so in a notice.
|
|
34
|
+
- **Dictation.** The mic beside Send, in the message box and in PiP's, dictates with the browser's own speech recognition, in the language the browser is set to. Words show in the box as they are heard and stay once the browser settles on them: at the caret while the box has the focus, after its text when it does not, with a space where they meet; words typed meanwhile stay too, and a phrase still being heard when you type or move the caret elsewhere finishes where it is, the next one going to the caret. It never sends by itself: tap the mic again (or Alt+V, which dictates into PiP's box while PiP is open, else into the session's) to stop, read it over, and send. Sending, leaving the session, closing PiP, or switching away from the tab stops it as well. What was heard is kept as a draft, like typing. While it listens the mic takes the accent, with a ring that breathes (still, with reduced motion), and the box says "Listening…". On a phone while Pi works, the mic takes Send's place until there is something to send. It needs a browser with the Web Speech API: Chrome, which sends the audio to Google's servers to recognise it, and Safari, on iOS too; where there is none (Firefox), the mic does not show. Browsers give a page the microphone only over https or on localhost, as Pi Pocket is served through the Cloudflare Tunnel, Tailscale Serve, or on this device. A blocked microphone, silence, a missing microphone, or no network says so in a notice.
|
|
34
35
|
- **Long pastes.** Pasting more than 20 lines puts a placeholder such as `[Pasted text #1 · 240 lines]` in the box; the message goes out with the text in its place.
|
|
35
36
|
- **Files at a tap.** Inline code paths in Pi's replies (`src/app.ts`, `app.ts:42`), Markdown links to local paths (such as `[config](/etc/app/web.env)`), file mentions in messages, read/write/edit cards, and Changes open a viewer: text with line numbers and syntax colors (Markdown rendered too), images, and folders to browse, with **@ Mention** to put the file in the message box. While the Files tile is open, they open there instead of in a sheet. Opening a file that is already shown reads it again, so after an edit the viewer shows the new text; the old text stays on screen until the new text arrives. Someone invited to one session sees its folder only, and only the owner opens Pi's own folder and Pi Pocket's data. For the owner, Ctrl+click (⌘+click on a Mac) on such a path, or on a row in the Files tile, shows it in the file manager of the machine Pi Pocket runs on (Files, Dolphin, Finder, Explorer), selected in its folder; so does the folder button in the viewer, with a mouse. It opens on that machine, not on the device you click from.
|
|
36
37
|
- **Files tile.** Menu → **Files** (or Alt+E, `/files`, or the launcher; the folder button in the top bar, where the pane has room) shows the session's folder beside the conversation on wide screens, where the Browser and People panels dock (one of the three at a time), and full screen on phones. Its bar has a switch between **Files** and **Changes** (with the count of changes), the folder's path, and close. **Files** is a tree of the folder that opens as you go (changed files carry an M, A, or D, folders holding changes a dot, and arrow keys move through it), a **Go to file** box that matches across the whole folder as the `@` menu does, and the file you pick, beside the tree when the tile is wide enough (600px) and in its place when not. **Changes** is the review below. Drag the tile's edge to resize it. Esc closes a file open over the tree, and then the tile where it covers the conversation, as back does.
|
|
37
38
|
- **Find in session.** Ctrl/⌘+F, `/find`, or Menu → **Find in session**: every message, command, and note in the session, earlier history included, newest first; tap one to jump to it.
|
|
38
39
|
- **Stop with Esc.** Esc twice stops Pi while it works.
|
|
39
40
|
- **Session titles.** A session is named after its first message; a long first message, or one that runs a skill or prompt template (`/skill:name`, `/review …`), gets a short title written by the session's own model (its cost counts as the session's), unless someone renamed it first. A command's title is written from what it sends, not only its name. A reply that is no title, such as a model thinking aloud or one cut off at its length limit, leaves the first message's.
|
|
40
|
-
- **Prompt templates.** Pi's prompt templates (`~/.pi/agent/prompts/*.md`, the project's `.pi/prompts/*.md`, and the paths in Pi's settings) show up as slash commands: `/review src/auth.ts` sends the `review` template with its arguments filled in. Pi's skills do too, as `/skill:name what to do`: Pi gets the skill's instructions with the request.
|
|
41
|
+
- **Prompt templates.** Pi's prompt templates (`~/.pi/agent/prompts/*.md`, the project's `.pi/prompts/*.md`, and the paths in Pi's settings) show up as slash commands: `/review src/auth.ts` sends the `review` template with its arguments filled in. Pi's skills do too, as `/skill:name what to do`: Pi gets the skill's instructions with the request. The `skills` setting of Pi's `settings.json` works as in Pi: `-path` and `!pattern` leave skills out, `+path` puts one back, and a relative entry starts from Pi's folder (since 0.28.0).
|
|
41
42
|
- **Project trust.** A project's own skills (`.agents/skills`) load only in a project Pi trusts, as in Pi's terminal app. When a session's project has some and nobody has decided, the owner is asked above the message box: **Review** says what trusting it loads, here and in Pi's terminal app, and offers to trust the folder, the folder above it, or not; **Don't trust** answers at once, and **Not now** (×) puts the question off in that tab. `/trust` or Menu → **Project trust** changes the answer later. Answers are saved where Pi's terminal app keeps its own, so a project trusted there is trusted here too. Pi has the skills from its next message. A project's `.pi/skills` load until it is told "Don't trust", then stay out too (Pi's terminal app asks before loading them at all); the sheet lists both kinds and says what each answer does to them. Only the owner is asked.
|
|
42
43
|
- **Changes.** The Files tile's **Changes** tab (or the count of lines added and removed in the top bar, `/changes`, or Menu → **Changes**): every uncommitted change in the session's folder as one review, file by file. Summary counts include new text files before and after staging (an untracked one over 2 MB shows no count); binary files have no line counts. Each file has a header that stays in view while you scroll its lines, with a fold chevron, what kind of change it is (M, A, D, or R in a small tile), its counts, and a **Viewed** checkbox button that folds the file; viewed files stay folded on this device until their diff changes again, and the summary says how many you have seen. Diffs show side by side when there is room and unified when not (Auto, Unified, or Split, as you pick, with long lines wrapped or not), with line numbers on both sides, syntax colors, and the words that changed within a line marked; a changed line is paired with its new version by likeness, not just position. The unchanged lines between changes are a tap away, a few at a time or all at once, read from the file as it is now (and only when it still matches the diff). Tap a line number to open the file there. A tree of the changed files (beside the diffs when wide, behind **Files** when narrow) jumps to one, a filter narrows them, and **π only** keeps the files Pi edited. Diffs load as they near the screen, a few at a time, and the review looks again a moment after Pi moves on. Keys: `j`/`k` the next or previous file, `n`/`p` the next or previous change, `v` viewed, `s` the layout, `w` wrapping. From a file's header, **↺** (tapped twice) puts it back as the last commit has it, or deletes it if it is new; Pi is told, and it waits while Pi works. A file with a merge conflict, or a rename, is left to git. Outside a repository it lists Pi's edits alone. Someone invited to one session sees the changes in its folder only.
|
|
43
|
-
- **Running now.** Menu → **Running now** (also on the sidebar's rail)
|
|
44
|
+
- **Running now.** Menu → **Running now** (also on the sidebar's rail and in the launcher) shows, in the conversation's place as the subagents board does, everything at work and everything scheduled in the sessions you can see. A **Coming up** timeline at the top has a lane per session: its scheduled messages as marks at their times (a diamond for a repeat, a ring for one that goes out once, amber while a spend limit or a lost right to steer holds it), a bar for how long the session has been at work, and a line at now; 24h, 3d, or 7d, it scrolls sideways, hovering a mark says what and when, and hovering (or tapping) a session's bar shows the last message sent to it, which its run works on. Under it, filter pills (All, Running, Scheduled, Needs approval, Held) and a search, then one row per session: the session, with its folder, Busy, calls to approve, and **Stop** on one line under its name; **Now**, what is at work there from Pi Durable's task graph (answers, tool calls, subagents, compactions, background tasks, shell and extension commands, PiP's follows and watches) with how long each has been at it, Stop where it can stop, and the session's model and spend; and **Schedule**, its scheduled messages with the next time, the repeat in words, and how many times each went out. A schedule picked there or on the timeline opens at the side on a wide screen, under the rows on a narrower one, and in a bar at the bottom on a phone: its message, repeat, next time in its own zone, who set it up, its next five times, **Open session**, and **Cancel**; **Needs you** (calls waiting for approval, held schedules) and **Next up** stay beside it. Esc, back, or × closes it; it asks the server again every 2 seconds while it shows.
|
|
44
45
|
- **Watch a pull request.** Menu → **Watch pull request**, `/watch` (or `/watch 123`, `/watch <PR address>`), or Pi's `watch_pr` tool, which it can start after opening a PR (Pi only for its folder's repository, by number; a person for any): until the PR is merged or closed, Pi Pocket looks at it on GitHub every few minutes with the `gh` command signed in on the server, and tells Pi in the session what needs doing, as a message sent through the watch for whoever set it up: checks that failed on its last commit (once all of them finished, with the end of each GitHub Actions log), conflicts with its base branch, and new comments and reviews. Only comments from the repository's owner, and from organization members and collaborators whom GitHub says can write to it, count, and bots' reviews (a member may only read, a collaborator only triage: `gh` asks GitHub, at most every ten minutes for each person, and GitHub tells only an account that can push there, so on a PR where yours cannot, such as a fork's PR to someone else's repository, only the owner's count, and the watch says so); your own account's (which Pi posts as) only when they mention @pi in their own words (not in a quote or code), so Pi never answers itself. Comments keep their lines (a suggested change is code), 30 at most in a message (read newest first, so a burst never hides the new ones); each is told once, and what does not fit in one message comes in the next; nothing goes while Pi is busy there or, with take turns on, while someone else drives (the bar says it waits, and nothing counts as failed); and a watch sends 10 messages at most. While Triggers is off it asks GitHub nothing. A bar above the message box shows the PR, its checks, and how many messages went, with **Stop**. It ends, with a line in the chat and a notification, when the PR is merged or closed, when there is more to tell than it may send, after two weeks with nothing new, or after an hour of looks that failed (the bar says why). Logs reach Pi fenced as data, which nothing in them can end early, and titles, check names, and branches come on one line, quoted, as data too. It needs `gh` installed and signed in (`gh auth login`) on the server, on GitHub Enterprise hosts too: a host other than github.com is used only when `gh` is signed in there (`gh auth login --hostname <host>`; a token only in `GH_ENTERPRISE_TOKEN` does not count), for Pi, PiP, and people alike, and Pi names a PR by address only on github.com or its folder's own host.
|
|
45
46
|
- **Watch a repository.** Tell PiP in plain words, such as "watch acme/api: when CI fails on main, fix it and tell me" or "when I open an issue labelled pi in acme/web, work on it": it sets up a watch that looks at the repository on GitHub every few minutes with `gh` (no public address needed, unlike a webhook), and what is new there (issues and pull requests opened, CI failing on a branch, releases, someone writing @pi, as a word of its own, in a comment or an issue) comes to PiP, or to a session you name, with your instructions; PiP then acts on it: it starts a session in the repository (its checkout here, or a clone it makes in the data folder's `repos/`), sends it the task, follows it, and tells you what came of it. A watch can be narrowed to a label, to issues assigned to you, or to a branch's CI (mentions of @pi are not narrowed). CI is the branch's own runs: pushed to it, scheduled, started by hand or through the API, or started by another workflow, in the repository itself, never a pull request's or an issue's (a renamed repository keeps working). Only repositories `gh`'s account can push to can be watched or worked on, and issues and pull requests count only from the repository's owner, and organization members and collaborators whom GitHub says can write to it (and bots' pull requests), unless you turn on **From anyone** on the watch in Menu → Webhooks and watches (PiP cannot); @pi always only from them. PiP works in a checkout of a session you started, or in a clone it makes, which appears only once complete (a clone a restart cut off leaves a `~part-…` folder, removed at the next clone of that repository); a different folder already where the clone goes is reported, never overwritten. While Triggers is off, watches wait and ask GitHub nothing; while PiP is off, a watch to PiP holds what it found, and its note says so. What came from GitHub is fenced as data, each thing is told once, ten in a message and twelve messages an hour at most (the rest come next), and a look that fails is tried again, less often each time, with the reason shown. Menu → **Webhooks and watches** lists the watches, to remove one; or ask PiP ("what are you watching?", "stop watching acme/api"). PiP can also start a PR watch on a session ("see acme/api#12 through"), and Pi's own `watch_pr` takes a PR in another repository it can push to by its address or `owner/name#12`, telling Pi to work in a checkout of it. Part of the **Triggers** extension.
|
|
46
47
|
- **Webhooks.** Menu → **Webhooks and watches**: an address that other services (GitHub, a deploy, a monitor) post to, each post becoming a message to Pi in a session, or to PiP, as the work of whoever made the hook: their instructions first ("When a deploy fails, find out why and fix it"), then what was posted, trimmed of noise such as API addresses, and fenced as data. PiP gets them as folded cards and decides what to do: start a session, message one, or tell you. A GitHub hook is signed: GitHub gets the address and, separately, a secret (its Payload URL and Secret), and a post gets in only with GitHub's signature made with it, so whoever sees the address (the repository's admins do, in its settings) cannot post as the hook. Unless a GitHub hook is made **From anyone**, what people outside the repository wrote does not reach Pi (the repository's people are its owner, and the organization members and collaborators whom GitHub says can write to it, asked through `gh`, which must be signed in to the host and able to push there, or else only the owner counts; bots count on pull requests and what is said on them, never on issues): a post an outsider started (their issue, comment, pull request, review, or discussion) is dropped with a 202 that says so; in a post the repository's people started, the body of anything an outsider wrote in it (the issue under a member's comment, a review thread's comments) is left out, its title kept; a workflow run goes only when a branch of the repository itself started it (a push, a schedule, a manual or API dispatch, or another workflow), so one a pull request (a fork's too), an issue, or a comment started is dropped, and so is one whose head repository GitHub does not show; workflow jobs, check suites, and check runs do not say where their run came from, so they are dropped too, as are a commit status on no branch of the repository (a fork's commit) and a security advisory someone reported; and pushes, releases, and other posts that name no author go as they came. A hook for another service has the secret in its address instead: anyone who has the address can message Pi as the hook's person. **New secret** shuts out the old one, for an address or a secret that got out. Anything else gets 404. A post GitHub sends again goes to Pi once, GitHub's ping gets an answer and is nothing for Pi, a hook takes 30 posts an hour of up to 5 MB each (the server reads eight at a time, two to one hook, each within 15 seconds; past that, 503 with Retry-After), a hook to PiP answers 503 while PiP is turned off, and a post that cannot go now (someone else drives, a spend limit) gets a 409 that says no more. Services must be able to reach the server: through a tunnel, a public address works for GitHub. People who can steer make hooks for the sessions they can reach; each sees their own, the owner every one. The watch and webhooks are the **Triggers** extension: turned off, watches wait and hooks answer 503.
|
|
47
48
|
- **Spend and limits.** Menu → **Spend** shows a large total and usage bars (against a limit, or the largest spend in that group): what Pi spent per person (the work goes to whoever asked for it) and per session, subagents included. The owner can limit a session or a person: past the limit Pi takes no new messages there, scheduled messages and goals stop, a run that crosses it stops, and subagents' reports wait instead of starting Pi again: the subagents bar says why (the owner gets **Raise it**), and they go to Pi together once the limit is raised, those that were in the queue when the run stopped included. The status line shows a session's spend and limit; for a session with a limit that started linked sessions (Agent Teams), the spend it shows, here and in the sheet, is the team's, as its limit counts it. PiP's row shows its limit too, and PiP's notices (such as a stop at its limit) show in its panel. Spend per person counts from the first start of a version with this feature; what was spent before shows for its sessions only.
|
|
48
|
-
- **A session's folder.** **New** (or Alt+N) opens a folder picker laid out as a desktop's file dialog, in the folder of the session you are in (or the server's folder, on the home screen): the path on top (tap a part to go back up, or its end to type a path), places at the side (Home, Computer, and recent folders), the folders where you are, and **Cancel** and **Open** at the bottom, with **Own git worktree** and **Show hidden** beside them. With a mouse, a click selects a folder and a double click goes into it; on a touch screen, a tap goes into it. **Open** starts the session in the selected folder, or in the one you are in, as the **Folder:** line says. Keys work as in a file dialog: arrows, Enter, Backspace to go up, letters to jump, `/` or Ctrl+L to type a path, Ctrl+Enter to open. The star on the **Folder:** line keeps that folder among the places as a favorite (tap it again to let it go). Favorites are each person's own, saved on the server, and change at once on all their devices; while New session is open, Ctrl+1…9 (⌘1…9 on a Mac) starts a session in one of the first nine, with **Own git worktree** as it is set. **New folder** makes a folder where you are and goes into it; a typed path that is not there yet offers **Create it**. Menu → **Working directory** (or `/cwd`) moves a session with the same picker. Someone invited to one session cannot browse or make folders. The launcher lists these too: **New session here** for the folder you are in, and **New session in** and its name for each favorite; each starts a session there at once, without a worktree of its own.
|
|
49
|
+
- **A session's folder.** **New** (or Alt+N) opens a folder picker laid out as a desktop's file dialog, in the folder of the session you are in (or the server's folder, on the home screen): the path on top (tap a part to go back up, or its end to type a path), places at the side (Home, Computer, the server's default workspace when it is another folder, and recent folders; pin the default workspace there to start every new session in it, in this browser, since 0.28.0), the folders where you are, and **Cancel** and **Open** at the bottom, with **Own git worktree** and **Show hidden** beside them. With a mouse, a click selects a folder and a double click goes into it; on a touch screen, a tap goes into it. **Open** starts the session in the selected folder, or in the one you are in, as the **Folder:** line says. Keys work as in a file dialog: arrows, Enter, Backspace to go up, letters to jump, `/` or Ctrl+L to type a path, Ctrl+Enter to open. The star on the **Folder:** line keeps that folder among the places as a favorite (tap it again to let it go). Favorites are each person's own, saved on the server, and change at once on all their devices; while New session is open, Ctrl+1…9 (⌘1…9 on a Mac) starts a session in one of the first nine, with **Own git worktree** as it is set. **New folder** makes a folder where you are and goes into it; a typed path that is not there yet offers **Create it**. Menu → **Working directory** (or `/cwd`) moves a session with the same picker. Someone invited to one session cannot browse or make folders. The launcher lists these too: **New session here** for the folder you are in, and **New session in** and its name for each favorite; each starts a session there at once, without a worktree of its own.
|
|
49
50
|
- **Branch.** The top bar shows the git branch the session's folder has checked out, under the session's title beside the folder, and follows it when Pi or anyone else switches (in a terminal too, within seconds). Tap it (or Menu → **Branch**, the launcher, `/branch`, or the branch in Changes, which stays in sight however long the folder's path) for the branch picker, down from it: the folder's branches with the current one first, then the newest, each with its last commit and how far it is ahead of or behind its remote branch, and the remote branches it has no local branch for. Type to search; a name that is no branch yet makes one from what is checked out (spaces become dashes), and a remote branch becomes a local one that follows it. Uncommitted changes come along, and when git would overwrite them it says so and nothing changes. A branch checked out in another worktree is listed but switched to only there. Switching changes the files under Pi, so as with moving the session to another folder it waits while Pi works and, while taking turns, is the driver's; Pi is told. Viewers see the branch; someone invited to one session can look but not switch.
|
|
50
51
|
- **Worktrees.** A new session (the New session sheet) or a fork (the message sheet) can work in a git worktree of its own: a branch, apart from the folder it came from, which starts with that folder's files as they are. Menu → **Worktree** removes it (not while Pi works in it); its branch stays.
|
|
51
52
|
- **Continue a Pi session.** A session of Pi in the terminal can carry on here. The owner picks it from **Continue a Pi session** in the New session sheet (or the launcher): Pi's sessions on this computer by folder, newest first, with a search through their titles, folders, and words, and for one its folder, model, and last messages. **Continue in Pocket** makes a new session in its folder, with its model when that one is signed in here, and its whole conversation to read. Pi gets the context Pi itself builds from the file: what a compaction summarized, and Pi's context edits, stay as Pi had them. Pi's system prompt and extensions' state stay behind, and nothing Pi did runs again: a tool call that never finished gets a result saying so. The session's file is only read. The list marks sessions already continued here, and says when Pi went on in the terminal since.
|
|
52
53
|
- **Export.** Menu → **Export as Markdown** (or `/export`): the whole history as a Markdown file, with tool calls folded into `<details>` blocks.
|
|
53
|
-
- **Any provider or model.** Uses Pi's own model runtime and sign-ins (`~/.pi/agent/auth.json`): pick a model and thinking level per session from the menu that opens up from the model chip in the message box (arrows and Enter pick, with a search box when there are many models), and sign in to providers (API key or subscription) from an inline card in the Providers sheet; expired sign-ins come first with a warning pill. API keys cannot be empty or only spaces. A failed sign-in shows a short message, technical details folded away, and **Start again**. A provider search with no matches offers **Clear search**. Pi’s `enabledModels` setting supplies the **Scoped** list, using Pi’s own pattern matching (including wildcards and thinking-level suffixes). When any scoped models are available, **[scoped | all]** beside the **Model** heading switches between that list and every model with a configured sign-in; the active choice uses the primary color. Tab in the search box (or in the picker, when it has no search box) switches it too, also when the search has no matches; from the picker's other controls, Tab moves the focus. On a touch screen, each choice takes a tap about 40px across. Each opening starts scoped; without a scope, when no pattern matches, or when `/model …` searches for models only outside the scope, it shows all instead. Switching the list keeps the search and changes no model or setting. The default-model picker has the same switch. New sessions start with the owner's default model and thinking level: **Make default** under the thinking levels makes the session's the default, and Menu → **Default model** (or the launcher) picks one without changing a session; without one, a new session starts with a trusted project's model/thinking default, then the last model anyone picked, then Pi's global default. To use project defaults, Menu → **Default model** → **Clear owner default: use project defaults, then last picked**. A project pin needs both `defaultProvider` and `defaultModel` in the final session folder's `.pi/settings.json`; `defaultThinkingLevel` is optional (`off` when omitted) and limited to that model's levels. Thinking-only project settings do not change another source's pair. Untrusted settings use normal fallback; a settings-only project appears in the owner's trust flow. Trust affects only later new sessions, never the open one, and no project setting can grant itself trust. Invalid consulted trusted settings stop creation with a contained error, without a model swap. Known unsigned project models stay selected. Imports, forks, subagents, manual choices, and PiP's own conversation keep their previous behavior. Extra per-project skill/prompt paths and per-project run policy are not supported yet ([project defaults](customizing.md#project-model-defaults-for-new-sessions)) A model is always one a person chose: a default that is not signed in now stays the default (the chip shows it, and the first message says why it fails) rather than give way to another model, and with no model chosen anywhere a new session starts with none until someone picks one. A subscription sign-in that its provider will no longer renew (OpenAI's refusing a refresh with `invalid_grant`, say) is found when the owner opens the Providers sheet, when a subagent on another model or PiP is about to use one of its models, or when a run fails on it: the sheet marks the provider **needs sign-in** with what the provider said, the model menu marks its models, the owner (alone) gets a notice, and subagents on other models and PiP use none of its models until someone signs in again. A session on one of its models, and a subagent on that session's model, are not checked first: they try it, and their runs fail where you see them. **Models for subagents
|
|
54
|
+
- **Any provider or model.** Uses Pi's own model runtime and sign-ins (`~/.pi/agent/auth.json`): pick a model and thinking level per session from the menu that opens up from the model chip in the message box (arrows and Enter pick, with a search box when there are many models), and sign in to providers (API key or subscription) from an inline card in the Providers sheet; expired sign-ins come first with a warning pill. API keys cannot be empty or only spaces. A failed sign-in shows a short message, technical details folded away, and **Start again**. A provider search with no matches offers **Clear search**. Pi’s `enabledModels` setting supplies the **Scoped** list, using Pi’s own pattern matching (including wildcards and thinking-level suffixes). When any scoped models are available, **[scoped | all]** beside the **Model** heading switches between that list and every model with a configured sign-in; the active choice uses the primary color. Tab in the search box (or in the picker, when it has no search box) switches it too, also when the search has no matches; from the picker's other controls, Tab moves the focus. On a touch screen, each choice takes a tap about 40px across. Each opening starts scoped; without a scope, when no pattern matches, or when `/model …` searches for models only outside the scope, it shows all instead. Switching the list keeps the search and changes no model or setting. The default-model picker has the same switch. New sessions start with the owner's default model and thinking level: **Make default** under the thinking levels makes the session's the default, and Menu → **Default model** (or the launcher) picks one without changing a session; without one, a new session starts with a trusted project's model/thinking default, then the last model anyone picked, then Pi's global default. To use project defaults, Menu → **Default model** → **Clear owner default: use project defaults, then last picked**. A project pin needs both `defaultProvider` and `defaultModel` in the final session folder's `.pi/settings.json`; `defaultThinkingLevel` is optional (`off` when omitted) and limited to that model's levels. Thinking-only project settings do not change another source's pair. Untrusted settings use normal fallback; a settings-only project appears in the owner's trust flow. Trust affects only later new sessions, never the open one, and no project setting can grant itself trust. Invalid consulted trusted settings stop creation with a contained error, without a model swap. Known unsigned project models stay selected. Imports, forks, subagents, manual choices, and PiP's own conversation keep their previous behavior. Extra per-project skill/prompt paths and per-project run policy are not supported yet ([project defaults](customizing.md#project-model-defaults-for-new-sessions)) A model is always one a person chose: a default that is not signed in now stays the default (the chip shows it, and the first message says why it fails) rather than give way to another model, and with no model chosen anywhere a new session starts with none until someone picks one. A subscription sign-in that its provider will no longer renew (OpenAI's refusing a refresh with `invalid_grant`, say) is found when the owner opens the Providers sheet, when a subagent on another model or PiP is about to use one of its models, or when a run fails on it: the sheet marks the provider **needs sign-in** with what the provider said, the model menu marks its models, the owner (alone) gets a notice, and subagents on other models and PiP use none of its models until someone signs in again. A session on one of its models, and a subagent on that session's model, are not checked first: they try it, and their runs fail where you see them. **Models for subagents** gets a full-height pane on the right of the owner's Providers sheet on wide screens, and comes first on phones. It lists every signed-in model by provider, with a box to find one when there are many: each one checked is a model Pi may start subagents and linked sessions on; with none checked (the default) they run on their session's model, and with some checked they run only on those, never on the session's own model unless it is checked (see Background subagents; `subagentModels` in `~/.pi-pocket/config.json`). A tap changes that one model alone, so quick taps, and two tabs at once, keep every choice. An allowed model that is not signed in now stays listed, marked, so it can be taken off. Star a model in Providers to save it as a favorite, independently of its subagent checkbox. **All models / Favorites** filters this list and the session/default-model picker; favorite models come after the current model and before other models in the picker, within the active scope. Favorites belong to the signed-in person in this browser and survive reloads; they do not sync between devices.
|
|
54
55
|
- **Multiplayer.** Any number of browsers can watch and steer the same session live. The status line under the message box shows how many are here, how full the context is (after a compaction, an estimate marked ~ until the next answer measures it), the cache hit rate, the cost, and a pill that says whether Lancet Guard is on (it opens Extensions). **Reply speed** in Appearance (or the launcher) adds how fast the last answer came: its tokens per second and how long its first token took (a response delivered in one buffered flush has no speed, only that wait). It is off until you turn it on, in each browser. On a touch screen, a tap on the line says in a notice what its items mean. On a narrow screen the line keeps to one row where it can. Where it does not fit, it gives up these in turn, only as far as it must: the speed's long words ("42 tok/s · 1.2s"), "1 here" while you are alone, the word "guard" (the shield stays), the word "context" (the meter stays), the cache, and the wait for the first token. "Sign in another device" makes a one-time invite link, a QR code, and a short code to type on the other device's sign-in screen. The owner can tick **Sign in as me (owner)** to sign their own other device in as the owner, with the owner's notifications, instead of as someone new. Messages show who sent them.
|
|
56
|
+
- **Profile pictures.** Menu → **Your name** (or the round button at the bottom of the side rail) has **Add photo** and **Remove photo**. The picture is cropped to a square and shrunk in the browser, kept in the data folder, and replaces your initials in the people lists, the rail, and on your messages for everyone who can see you.
|
|
55
57
|
- **Working together.** The top bar shows who else is in the session (an avatar with a mark that greys when their tab is in the background, and how many more), and "Alex is writing to Pi…" warns before two people steer at once. The **People** panel opens beside the conversation on wide screens, where it takes the Browser panel's place, and as a sheet on phones. Its header counts the people here; the roster shows their online or away state, typing, and role. A **Take turns** card starts or turns off shared driving with the same permissions as the menu. It has:
|
|
56
58
|
- **Chat** for the people in the session, which Pi does not see. Your messages are right-aligned accent bubbles; other people's are left-aligned, with their name and time above. Quotes sit above the bubble, and the pill-shaped message box keeps a dismissible quote strip. The latest pin stays above the chat. Type `@` to mention someone (they get a notice wherever they are), tap **Discuss** under a reply of Pi's to quote it, and tap a chat message to **Send to Pi**, pin, or copy it. Changes show up here as activity lines ("Alex stopped the run", "Tanner switched the model to …", "Alex allowed the bash call: …"), and as a notice to everyone else in the session.
|
|
57
59
|
- **Pinned** replies and chat messages.
|
|
@@ -59,9 +61,10 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
59
61
|
- Under Pi's answers: emoji reactions, **Discuss**, and **Pin**. Queued messages show who queued them. Approved or denied tool calls show who decided.
|
|
60
62
|
- **Take turns.** Menu → **Take turns**: one person drives and only they send to Pi or change its settings. Others tap **Ask to drive**, the driver hands over, and anyone can take the wheel when the driver has left (the owner always can). Anyone who can steer can still stop a run.
|
|
61
63
|
- **Roles and invites.** An invite can let someone **steer** or make them **view only** (they read, react, and chat, but cannot send to Pi, approve, or upload). It can cover **every session** or **only this session**, and lasts 15 minutes, an hour, a day, or a week (**Expires after**); either way it works once, and a restart keeps it. Changing what the sheet's invite grants, or how long it lasts, ends the one it showed; **New invite** makes another and leaves the one before working. Only the owner can make an owner invite (**Sign in as me (owner)**): it makes no one new, but signs the device in with the owner's token, so it has full control, works once, and always expires in 15 minutes; rotating the owner token (`--rotate-token`) signs out every device signed in that way, and ends owner invites not yet used. Menu → **People** lists everyone, who is online, and when the others were last here. The owner can change what each person may do or remove them. The session list shows who is in each session, and a dot marks new chat messages.
|
|
62
|
-
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished, Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel, or
|
|
64
|
+
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished, Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel or Tailscale Serve, or another tunnel such as ngrok in front of **This device only** (`--access local`). On iPhone, add Pi Pocket to the home screen first. The server signs pushes with its own keys in `~/.pi-pocket/push.json`.
|
|
63
65
|
- **Built-in browser.** Menu → **Browser** (or Alt+B, `/browser localhost:5173`, or the globe in the top bar while a page is open; on a phone, a dot on the places button by the message box says so) opens a real Chromium page that runs on the server: beside the conversation on wide screens, full screen on phones. Type an address (`localhost:5173`, `example.com`), or (the owner) tap a row under **Running on this machine** on the start screen; a green dot in the rounded address field marks an open page. Tap, drag to scroll, and type into the page (the keyboard button sends text from a phone). The size button switches between fitting the panel (the page follows the panel when it changes size), desktop, phone, and tablet sizes, and the console button shows the page's logs and errors, with a warning-colored error count. Pi's `browser` tool uses the same page: it opens addresses (dev servers, HTML files on the machine, any site), reads a snapshot of the page's text and controls, clicks, types, takes screenshots it can see, reads the console, and runs JavaScript in the page, while everyone in the session watches. Each session has one page, in a browser context of its own; links that open a new tab open there instead, and dialogs are accepted. Anyone in the session can watch; using the page takes steering rights (and the wheel, while take turns is on), the addresses people open show in the chat, and only the owner opens files from the address bar. The browser reaches what the server reaches, `localhost` and its network included, and Lancet Guard does not check it (see SECURITY.md). A restart closes the pages, and each opens again at its last address and size. Where the panel covers the conversation, Esc closes it, unless the page has the keys (then Alt+B does). In plan mode Pi may look at pages but not click, type, or run scripts in them. It needs Chromium, Chrome, Brave, or Edge on the server (or `PI_POCKET_BROWSER`); the owner can turn it off in Extensions, which closes the panel too.
|
|
64
66
|
- **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. The `artifact_inline` tool is the same store for HTML only (`content` or `edits`, no path): its call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but `artifact_inline` refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `artifact_inline` only in sessions that have the tool, and says that only a direct call shows a card. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's.
|
|
67
|
+
- **All artifacts.** The rail's artifact button opens every artifact in every session you can see, grouped by session (archived sessions are left out), newest first. Each row shows its type, size, age, and the number of its current (latest) version, as `v3 / 3` of the versions it has (`v1` when it has one). A tap opens that version in its session. The launcher's **All artifacts** opens it too, which is the way on a phone. The list is `GET /api/artifacts`.
|
|
65
68
|
- **Design.** On by default (Menu → **Extensions** turns it off). A canvas beside the chat for Pi's HTML designs: prototypes, screens, one-pagers, and slide decks. A design is an artifact, so versions, the sandbox, saved state, and share links work as they do for any artifact. Open it from the rail, the places, **Open in Design** in the artifact viewer, or `/design-open` (with an artifact's id to open that one). On a wide screen the panel sits beside the chat; on a phone it covers the chat, and the way back keeps the canvas as it was. Since 0.26.0.
|
|
66
69
|
- **The canvas.** A picker of the session's HTML artifacts (newest first, variations together); the page in the artifact sandbox, at phone (390×844), tablet (820×1180), desktop (1280×800), or a custom size; fit or zoom, and a light, dark, or theme backdrop. A new design that Pi makes opens by itself, unless you are in a mode, have a draft, or it is a variation of the open design.
|
|
67
70
|
- **Versions.** A timeline of every version, side-by-side compare of two, and **Go back to this one**: it makes a new version that is a copy of the old one, assets included, and does not ask Pi. A repeated tap finds the version it made.
|
|
@@ -84,8 +87,8 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
84
87
|
- **Ask someone.** Off until the owner turns it on in Menu → **Extensions**. When Pi needs an answer that only someone outside the chat can give (a manager, a client, an expert), **Ask someone** under one of Pi's answers puts a request in the message box, and Pi writes the question with its `ask_someone` tool so that it stands alone: the background, the question, the options, and its recommendation. Nothing goes anywhere yet: the draft waits in **Questions for others** (the status line under the message box, the session menu, or the launcher), where you edit it, **Copy text**, or **Create link** for a day, a week, or a month. The link opens a page with no sign-in, the question, and a box for one answer and an optional name; then it closes. **Copy link**, **Copy message**, and **Share…** (on a phone) send it on; **End link** takes the page down. When the answer comes, a notice says so, and **Give to Pi** puts it in the message box, quoted and marked as someone else's view, for you to send. People who steer every session use it; viewers and people invited to one session do not. Since 0.22.0.
|
|
85
88
|
- **Waiting out provider limits.** When a provider's limit stops a run (a 429 or an overload, a Claude or ChatGPT usage window, a model's cap), Pi Pocket waits for it to clear and goes on by itself, instead of failing. It waits until the reset time the provider gave (or, with none, tries again at growing intervals), then sends one request to find out; if that gets an answer, the sessions waiting on the same limit go on, one at a time. The live line says what Pi waits for, when it tries next, and when the limit resets, with **Retry now**; **Stop** or **Interrupt** end the wait at once, and a message you send meanwhile waits in the queue as always. The session's square is a hollow square with a dot, also on peek tiles, and a subagent's row says it waits. One push goes out when a wait of ten minutes or more begins (Menu → **Notifications** → **Waiting for a limit**). It survives a restart. The owner sets the longest wait (**Wait for a limit** in the Providers sheet: Off, 1, 6, 12, or 24 hours; default 6): what waits is any reset time within that longest wait, load with no time given (an ordinary 429 or an overload), which is tried again at growing intervals for up to 30 minutes, and, since 0.24.0, a plan's usage limit with no time given (OpenAI subscription sharing, Z.ai, MiniMax, OpenCode Go), which is tried again about every 15 minutes, up to the longest wait, counted from the first failure across restarts. What fails the run at once, with the reset in the message where there is one: a window of days (Claude's 7-day window, a Codex window of over 300 minutes), a reset after the longest wait, a usage limit that names a window of days (daily, weekly, monthly), with or without a reset time, and a sign-in that expired or billing. Retry now sends one try each 30 seconds. It never picks another model. Since 0.21.0.
|
|
86
89
|
- **Prompt cache keeper.** On by default; `PI_POCKET_CACHE_KEEPER=off` turns it off. While a run waits on a tool call, Pi Pocket replays the last request that ended in a tool call, with `maxTokens` 1, at 90% of the cache's lifetime or 10 seconds early, whichever is sooner. It does so only when the expected savings are more than the cost. It keeps the 5-minute cache only: no idle warming, no 1h cache, no request with `cacheRetention` none, and no Anthropic thinking set by a token budget. It stops on a real cached request, when the run ends (PiP's too), on an error, at shutdown, or after 30 minutes. A warm request does not wait for a provider limit. Its usage counts in `pi.usage` and in the spend of the person and session that were paying when it started, and spend limits are checked before each warm. A restart drops the warm timers and does not replay warm requests.
|
|
87
|
-
- **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.19.0, Pi writes its tasks for subagents in ASD-STE100 (Simplified Technical English) and asks for their reports in it too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. Pi picks no model on its own: until the owner allows models for subagents (**Models for subagents** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model.
|
|
88
|
-
- **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. A session's last answer comes to PiP, in a report or a read, in parts of up to 12,000 characters; when it is cut, a note after the fence says how many characters are left, and PiP's `session_read` tool takes `answerFrom` (a character) to read the rest of that answer, part by part. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Open as a conversation** shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back.
|
|
90
|
+
- **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.19.0, Pi writes its tasks for subagents in ASD-STE100 (Simplified Technical English) and asks for their reports in it too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. Pi picks no model on its own: until the owner allows models for subagents (**Models for subagents** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model. A subagent's status line shows what the subagent itself cost, with no limit: the limit is its session's (since 0.28.0).
|
|
91
|
+
- **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. A session's last answer comes to PiP, in a report or a read, in parts of up to 12,000 characters; when it is cut, a note after the fence says how many characters are left, and PiP's `session_read` tool takes `answerFrom` (a character) to read the rest of that answer, part by part. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Open as a conversation** shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back. PiP follows its owner's standing instructions in `pip.md` in the data folder, such as the language of its answers (since 0.28.0, [customizing.md](customizing.md#pips-instructions)).
|
|
89
92
|
- **Resize.** At widths of 768px and above, drag PiP's left edge, top edge, or top-left corner to resize it, with the bottom-right corner fixed. The same zones are finger-sized on touch screens. Its size is remembered for each account in this browser and fits back inside the viewport when it shrinks. Phones use a bottom sheet with rounded top corners and a grabber; the model, context meter, and all four header actions stay available.
|
|
90
93
|
- **Choose PiP's model.** Tap the model chip in PiP's header to use the existing model and thinking picker for PiP alone, from Home or over a session. The chip and picker choices are disabled while PiP works. Saving also checks that PiP is idle. This header path does not change the last picked model for new sessions; **Open as a conversation** keeps its existing behavior. With no model, the welcome offers **Choose a model to use these suggestions**, which opens the same picker. Suggestions that send at once wait for a model; those that put text in the box stay usable, and choosing a model keeps the suggestions visible.
|
|
91
94
|
- **Files and images in chat.** Pick files with the attach button, paste files or images from the clipboard, or drop them into PiP's message box. Remove attachments before sending; upload status shows while they are saved. You can send files with text or on their own. They belong to PiP's conversation, not the session behind the panel. Images have previews and open full screen; other files show their names. As in normal chat, supported images go directly to an image-capable model and other files are given as saved paths. PiP does not choose a different model for you. Draft attachments stay when you close and reopen the panel.
|
|
@@ -119,11 +122,12 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
119
122
|
- **Extension settings.** A module can declare settings (on or off, text, a number, a choice, or a secret such as an API key); the owner changes them in Menu → Extensions under the module, with **Save settings**, and **Default** or **Clear** to put one back. A secret's value never leaves the server: the sheet shows only that it is set. Modules can also listen to what happens in the app (sessions made, renamed, and archived, messages, runs) and offer services to each other; Extensions says which ones offer a service. Since 0.22.0 ([docs/extensions/services-settings.md](extensions/services-settings.md)).
|
|
120
123
|
- **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**, which installs it turned off. An entry (since 0.27.0) says **What it can reach** in plain sentences, each marked with where it comes from: **In its code** (from the scan below: "Talks to openrouter.ai", "Uses your openrouter key, from Pi", "Runs git and gh", "Uses files it writes"), **Declared** (the hooks it sees with, such as "Sees tool calls, before they run", and changes to Pi's instructions or tools), and **Always** (it runs in the server with your rights, in every session, where Lancet Guard does not see its code), then what the scan found nothing for. The scan reads the code's text, so the code can reach more than it finds: the entry says so, and nothing claims an extension stays inside. When the installed files were edited since install, the entry and the question say that the summary is the pinned version's, not what runs. **What it adds** shows its tools and commands as code, and what it puts in the app; technical information is folded below. **Install and turn on** asks one question over the sheet: what it reaches, and that the scan reads text so the code can reach more, with **Cancel**, **Install turned off**, and **Install and turn on** (Cancel has the focus, Escape closes only the question, and the question stays until it is installed and on); **Install turned off** installs it without asking, and an installed one that is off has **Turn on**, which asks the same question. Before turning it on, read its source with **View source**, or install it off and **Ask Pi to review**. A theme's entry shows its picture in its own colors (dark and light side by side when it has both), what it changes from its files (its colors, a layout of its own, its fonts, its images), its palette with the values, and **Use it in this browser** and **Open Appearance** once installed. In **Updates**, a row says what an update adds to what the extension declares ("Declares more: sees tool results; 2 new tools", or "Declares nothing new") before its review; its code's changes are in the review's diff. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)). **What an entry reaches.** `GET /api/x/gallery/reach` (the owner's, like the other gallery routes) answers `{ entries: { [name]: … } }` for every entry of the index read now, each with the entry's `pin` so the app matches a result to the exact files it shows, so the app can show what each one can reach before it is installed. An extension gives `{ kind: "extension", commit, scanned: { network, keys, programs, files } }`: short words for the hosts its address literals name (`localhost`, standards' namespaces, `example.*`, and repository pages left out; `addresses it builds at run time` when it calls `fetch(`, `new WebSocket(`, or `http.request` with no host in its code, or gives one of them, or a `net`, `tls`, or `dgram` connection, an address it builds, also beside hosts it names), the keys it reads (`openrouter key from Pi`, an environment variable whose name has `KEY`, `TOKEN`, or `SECRET`, `Pi's auth.json`), the programs it starts (`programs it names at run time` when it imports `child_process` but names none, or loads code the scan cannot read: `eval`, `new Function`, `getBuiltinModule`, `process.binding` or `dlopen`, `import()` or `require()` of a name it builds, or a `.node` file), and the files it writes (`files it writes`, paths under `~/.pi/agent/`, or `your home folder`). The scan is by literal patterns on the code with its comments taken out: it tells what the code says, not what it does. A theme gives `{ kind: "theme", commit, palette: { colors, colorsLight } }` from its `colors.toml` and `colors-light.toml` (`null` for one it lacks). An entry that cannot be read (a download fails, or a file differs from the size or SHA-256 the index pins) gives `{ kind, commit, error }` and fails no other entry. Only the code files (`.ts`, `.js`, `.mjs`, `.cjs`) and the two palette files are read: from the installed copy when the entry is installed at the same commit and each file is as pinned, otherwise downloaded from the pinned commit with the checks every download has. Results are kept in `gallery/reach.json` in the data folder, by entry, commit, and pinned files, so the next answer downloads nothing for them; entries that fail are tried again, and three are read at a time.
|
|
121
124
|
- **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on), **Install new versions by themselves** (off), and **Beta updates** (off). **Beta updates** (since 0.27.0) also offers pre-releases, tagged `vX.Y.Z-beta.N` (GitHub releases marked as pre-release; npm's `beta` dist-tag): a git checkout takes the highest version among GitHub's non-draft releases (or the beta tags, when GitHub does not answer), and an npm install the newer of the `latest` and `beta` dist-tags. A beta is marked **Beta** in the sheet, the menu hint, and the notice, and its caution says that it may have bugs. With the setting off nothing changes: only stable releases are offered, a beta is never offered, and a running beta still gets the next stable release (`0.27.0` is newer than `0.27.0-beta.N`, and `0.27.0-beta.2` is newer than `0.27.0-beta.1`) but never an older one. Turning it off drops a beta found before. An install by itself also takes a beta, when both settings are on. A server from before 0.27.0 needs a restart (menu → Restart server) for the setting to work. An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
|
|
122
|
-
- **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (
|
|
123
|
-
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them.
|
|
125
|
+
- **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (in the provider controls), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
|
|
126
|
+
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them. An image starts to be made ready for the model as soon as it uploads, so a send seldom waits for it. In a session's message box (not PiP's), attached files stay across a reload, as the draft does, and leave with your sign-out; while a message is on its way, the box dims and holds what it sends, and if the send fails, it is all there to send again.
|
|
127
|
+
- **Code in your messages.** In a message you send, `` `code` `` and a fence of ` ``` ` lines show as code, the way Pi's replies show it, colored when the fence names a language (` ```js `). A span closes with as many backticks as opened it, a fence's lines stand on their own, and a stray or unclosed one stays text. Nothing else is formatted: `*`, `#`, lists, and spacing stay as typed, and @mentions outside code stay buttons. Only the display changes: Pi, exports, and ↑ get the message as written.
|
|
124
128
|
- **Rich replies.** Code blocks in Pi's replies show their language and a Copy button, with syntax colors for the common languages (no dependencies, so it works offline), and a block of more than 40 lines folds until you ask for the rest. Some show more than code, with the code a tab away: an `html` block (or a reply that is a whole page) is previewed as a page, inline, with its scripts off and nothing loaded from anywhere; **▶ Run** runs its scripts in the artifacts' sandbox, where it can reach the internet but not the app; an `svg` block is drawn as an image (tap it for full screen); and a `diff` or `patch` block opens in the diff viewer. While Pi is still writing, they show as code. Write cards color the file they write, and the file viewer previews `.html` files the same way, with Run. **Cards in the reply.** An `artifact_inline` call shows as a card in the reply, as the `html` block above with the artifact's name and version in its bar, an **Open** button for the artifact viewer at that version, and the same Preview/Code and Run/Stop; a failed, denied, or stopped call shows as a step with its reason instead. The result records the version its call made, so each card keeps showing its own: an update by Pi adds a new card, and earlier cards, in this session and a fork, do not change. A card's page is read from the artifact's own address, so whoever can see the session sees the card, a viewer and someone invited to this session alone included, and each can Run it. Once run, its page gets what an artifact's does: a follow-up for the message box (a notice for a viewer) and saved state under the artifact's id, shared with the viewer. A preview grows to fit the page, up to 1200 px, and a running page up to 900 px, then scrolls inside. On a phone the bar takes two lines. A viewer already open on an older version stays on it and offers "latest is vN" after an update. Only a call Pi makes itself is a card: one made inside a codemode script is one of its nested calls, and in PiP's panel the call is a line among its steps.
|
|
125
129
|
- **Images inline.** Attached images show as thumbnails (also in the composer before you send). When Pi writes `` with a path on the server (absolute, `~/…`, or relative to the session's folder), the image shows in its reply. Images a tool returns and SVG artifacts show inline too; an image Pi reads with `read` (often one you just sent) shows only when its call is opened, so it is not on screen twice. Tap any image to see it full screen. Only real image files are shown: the server checks a file's bytes, not just its name.
|
|
126
|
-
- **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, or Tailscale. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access.
|
|
130
|
+
- **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, Tailscale, or Tailscale Serve. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access.
|
|
127
131
|
|
|
128
132
|
## Limitations
|
|
129
133
|
|