pi-web-casual

A PI WEB plugin that adds one long-running conversation that is not attached to a repository.

Status: implemented (v1). Browser-only plugin: a project-free home holding a strip of conversations, opened from the Casual tab or the action palette. It has no server entry and needs no session-daemon restart.

What Casual does

PI WEB organizes conversations around projects and workspaces. That is the right shape for code and a poor fit for the rest of the day: what to cook, naming a playlist, explaining an article, planning a weekend. Casual gives those conversations one home by reusing PI WEB's own project machinery: a hidden project at ~/.casual-pi-web and a normal session inside it.

The chat is PI WEB's native chat, not a plugin reimplementation. Streaming, Markdown, tools, images, model selection, and compaction behave exactly as they do anywhere else, and the conversation is stored where PI WEB stores every other session.

It contributes:

• a Casual application tab;
• five palette actions: Open Casual Chat, New Casual Chat, Reset Casual Link, Change Casual Home, Set Up Casual Chat.

It behaves like this:

• One home, a few conversations, the same everywhere. The Casual tab keeps a numbered strip of conversations, all in the same hidden home. Click a number to switch, + to start another, × on the active tab to archive it; nothing reloads when you switch. The strip and the open conversation are stored with the home on the host, so the phone and the computer show the same ones, in the same order.
• The Casual tab is a chat with a strip. The tab embeds the real PI WEB chat in a same-origin frame with that frame's navigation, header, and workspace column trimmed away, so a project chat in the main column keeps working next to it. Above the chat sits the conversation strip and nothing else: there is no toolbar and no card around the chat, and every other control lives in the palette. Everything Casual does happens inside this tab; there is no second window.
• Hidden home. The Casual project is filtered out of the Projects sidebar, including its row, the project count, and the collapsed-heading summary. It remains a real project for PI WEB: it appears in the Change home chooser, and its sessions appear in Sessions while it is selected.
• The tab shows what the agent is doing. The Casual tab's ⁂ uses PI WEB's own status colors, the ones a project row would have shown: green while the agent works in the home, accent while a finished reply is still unread, untinted when nothing is in flight. The tab's tooltip and accessible name say the same thing. The accent clears once the reply has been read in the tab, so it never outlives the visit.
• New chat keeps history. New Casual Chat and the strip's + create another session in the same home and make it the active tab. The previous conversation stays in the strip and in Sessions; × archives through PI WEB and offers Undo in the strip, which is the practical way back because the home project row is hidden. Casual never deletes.
• Self-repair. Every render settles the strip against the host: it adopts the strip another browser wrote, drops tabs whose conversation was archived elsewhere, and falls back to a live conversation when the active one is gone.
• Automatic first run. The first Open chat or palette open creates and trusts ~/.casual-pi-web, starts a session, and reloads the page once into the Casual tab. There is no Add Project step.

Install

Requirements

• PI WEB 1.202610.3 or newer (browser plugin API v4). Tested against @jmfederico/pi-web 1.202610.3.
• Node.js 22.19 or newer only if you build from source. Installing the published package needs no toolchain.
• No session-daemon restart at any point.

PI WEB has no install-time version gate for plugins, so an older host installs the package and then refuses it at activation. The browser console shows PI WEB Casual requires PI WEB 1.202610.3 or newer, and no Casual tab is registered.

From GitHub

1. Open PI WEB → Settings → Pi packages.
2. Install https://github.com/paradise-runner/pi-web-casual.
3. Enable Casual under Settings → PI WEB plugins if it is not already on.
4. Reload the browser page.

From a release tarball

Download pi-web-casual-0.1.0.tgz from Releases and install that file under Settings → Pi packages, then enable Casual and reload.

From npm

The package is prepared as pi-web-casual but is not published yet. Use GitHub or a tarball until it is. Maintainers: see docs/how-it-works.md.

From source

See CONTRIBUTING.md. PI WEB does not compile TypeScript for local packages, so a checkout must be built before it is linked.

First run

1. Open the Casual tab, or Actions → Casual → Open Casual Chat.
2. Casual creates and trusts ~/.casual-pi-web, starts the first session, and reloads the page once into the chat.
3. Type in the normal composer.

The reload is one-time. PI WEB has no plugin API for registering a project, so Casual uses the host's own same-origin project and session endpoints for setup (docs/how-it-works.md). It lands in the Casual tab, where the chat is embedded.

If those requests are unreachable, the panel shows a setup card instead: add ~/.casual-pi-web yourself through Add Project, or choose an already-registered project as the home.

Use

Every one of these stays in the Casual tab: opening it, starting a conversation, and switching between them never navigates the page or replaces the project chat beside it.

The Casual tab never redirects you into the host chat view. It shows the card, and once a conversation is remembered it embeds that conversation directly. Setup and error states keep their own card with the controls needed to recover; a flow in progress leaves the chat on screen and reports itself in the strip.

While the conversation is open, the Casual project is the selected project, so its sessions are visible in Sessions like any other project's.

Limits (v1)

• A handful of conversations, not a workspace of them. One home, several conversations, no topics, folders, or per-conversation homes. Numbers follow position, so closing a conversation renumbers the ones after it.
• The strip has no agent status of its own. The ⁂ on the Casual tab still reports work and unread replies for the whole home; individual tabs do not carry their own dot yet.
• Archiving needs a host with the session lifecycle route. On an older PI WEB the × removes the tab and says so; the conversation stays in Sessions.
• Archived casual conversations are one click away, not one screen. The strip's Undo covers a misclick; beyond that, PI WEB's Archived list needs the Casual project made visible again, since the plugin hides it.
• One home per machine. The home folder is fixed at ~/.casual-pi-web unless you run Change home. The strip is shared by every browser that points at that machine, but two machines run two homes with their own strips and their own conversations.
• The shared strip is last-write-wins. The strip and the open conversation live in ~/.casual-pi-web/.pi-web/casual/state.json, written by whichever browser changed it last; the others adopt it on their next render, focus, or palette action. There is no merge and no conflict dialog. If that file cannot be read, Casual keeps working per browser and the strip stops syncing.
• No settings pane. PI WEB's plugin API has no Settings contribution, so the home folder and pointer are changed through the card's controls, not through configuration.
• Controls live in the palette. Once a conversation is remembered the Casual tab has only the strip, so Open, New, Reset Casual Link, Change Casual Home, and Set Up are palette actions. The card's buttons appear only in the states that show the card.
• The embedded chat is framed, not native to the panel. PI WEB's plugin API exposes no transcript component, so the Casual tab embeds the app's chat route in a same-origin frame and hides that frame's chrome. The frame is supervised, not trimmed once: it boots its own SPA, so the chrome keeps being hidden as the frame renders. A frame is also a second client instance with its own daemon connection.
• Best-effort chrome. PI WEB has no contribution point for hiding a project row, for a chat-only layout, or for a status color on an application tab, so the hidden row, the embedded frame's chrome trimming, and the tab's state depend on PI WEB's private shadow DOM and its machine status snapshot. Every render after activation is covered; on a cold page load the row can be painted for the moment before the plugin loads. If an update changes that markup, the Casual tab and the palette keep working, without the tint, and the selectors need work in src/browser/dom.ts.
• Project registration and status are not public API. First run uses the host's own endpoints, and the tab's status color reads the host's machine status snapshot (api/machines/<machineId>/status) every four seconds while the page is visible. If PI WEB changes them, first run falls back to the setup card and the tab keeps the last state it painted rather than showing a wrong one.
• API v4 only, PI WEB 1.202610.3 or newer. Older hosts accept the package but Casual refuses to activate, because they lack application panels, the selection service, and project discovery. PI WEB 1.202610.6+ logs a deprecation warning for every API-v4 plugin, including its own bundled plugins. Moving to API v5 would drop 1.202610.3 support.
• No deletion. Casual does not delete sessions, workspaces, or the home project. Manage history in Sessions.
• No telemetry. No analytics, no third-party calls, no server process. Messages go to the model provider you configured for PI WEB.

How it runs

A browser-only PI WEB plugin package. There is no server entry, no Pi extension, and no agent client: the plugin resolves the home project, keeps the strip of conversations, and embeds PI WEB's native chat in its own tab.

• Browser bundle in dist/browser, served by PI WEB directly from the installed package.
• Browser API v4. On this version the public catalog is only handed to API-v5 plugins, so discovery goes through the host's own project, workspace, and session routes; activation throws on hosts that lack the selection service, which is the version probe for 1.202610.3.
• Local copy of the pointer in localStorage (pi-web-casual:store:v2): casual project, workspace, strip, and active conversation.
• Shared copy of the strip and the active conversation in ~/.casual-pi-web/.pi-web/casual/state.json, through the host's workspace file route.
• Shadow-DOM integration isolated in src/browser/dom.ts.

Detail, including the bootstrap requests, discovery order, explicit-open intent, and shadow-DOM selectors: docs/how-it-works.md.

Development

npm install --ignore-scripts
npm run typecheck
npm run build

--ignore-scripts skips building the native dependencies of the PI WEB host package; this project only consumes its TypeScript declarations. There is no test suite yet; the manual checklist lives in CONTRIBUTING.md.

The generated dist/browser files are committed because PI WEB serves them from the installed package. CI verifies they match source.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and report security issues as described in SECURITY.md.

Decisions

• ADR 0001: One long-running conversation
• ADR 0002: The chat is PI WEB's native chat
• ADR 0003: Browser-only, with first-run bootstrap through host endpoints
• ADR 0004: Stay on browser plugin API v4
• ADR 0005: Best-effort private shadow-DOM integration
• ADR 0006: The Asterism toggles between the project chat and Casual (superseded)
• ADR 0007: Casual opens in its own browser tab (superseded)
• ADR 0008: The Casual panel embeds the chat in a same-origin frame
• ADR 0009: The Casual tab replaces the header button
• ADR 0010: The Casual tab reports agent activity
• ADR 0011: Conversations live in a numbered strip
• ADR 0012: The strip is stored with the home, so every browser sees it
• ADR 0013: Everything happens in the Casual tab
• Vocabulary
• Using Casual
• How Casual works

Related

• PI WEB — the web UI that hosts Casual.
• PI WEB plugin documentation — supported contracts, installation, and reload rules.
• Pi coding agent — the agent that powers PI WEB conversations.

License

MIT © 2026 Edward Champion.