From 18127996f17d87825949b254c112d3e1246c8150 Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Mon, 15 Jun 2026 01:24:44 +0200 Subject: [PATCH 01/31] docs: improve Pi web UI SEO positioning --- README.md | 12 +++++--- docs/404.html | 10 +++++- docs/_redirects | 6 ++++ docs/faq.html | 37 +++++++++++++++++++--- docs/index.html | 69 ++++++++++++++++++++++++++++++------------ docs/install.html | 27 ++++++++++++++--- docs/machines.html | 24 ++++++++++++--- docs/plugins.html | 27 ++++++++++++++--- docs/remote-first.html | 31 ++++++++++++++----- docs/robots.txt | 5 +++ docs/sitemap.xml | 45 +++++++++++++++++++++++++++ package.json | 17 ++++++----- 12 files changed, 256 insertions(+), 54 deletions(-) create mode 100644 docs/_redirects create mode 100644 docs/robots.txt create mode 100644 docs/sitemap.xml diff --git a/README.md b/README.md index d1d4e32..21165bc 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# PI WEB +# PI WEB — web UI for Pi Coding Agent [![CI](https://github.com/jmfederico/pi-web/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jmfederico/pi-web/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@jmfederico/pi-web)](https://www.npmjs.com/package/@jmfederico/pi-web) @@ -10,9 +10,9 @@ Website: ![PI WEB](docs/assets/pi-web-banner.png) -**Run AI coding agents on your own machine or server, keep them alive in real workspaces, and control everything from a browser.** +**Run Pi Coding Agent from a web UI, keep sessions alive in real workspaces, and supervise them from any device.** -PI WEB is a web control plane for [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent). Add your repositories once, open project workspaces and git worktrees, start agent sessions inside them, and come back later without losing the work. Your browser becomes the cockpit; your server becomes the persistent development environment. Start on your laptop, check in from your phone, and continue from an iPad or another machine whenever that is the device you have at hand. +PI WEB is a web UI for [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) that keeps agent sessions running on your own machine or server. Add your repositories once, open project workspaces and git worktrees, start sessions inside them, and come back later without losing the work. Your browser becomes the cockpit; your server becomes the persistent development environment. Start on your laptop, check in from your phone, and continue from an iPad or another machine whenever that is the device you have at hand. ![PI WEB demo](docs/assets/pi-web-demo.gif) @@ -32,6 +32,10 @@ Agentic development works best when agents are not trapped inside a single local PI WEB connects those two worlds. The work stays in the server-side environment while you move between devices: laptop for deep focus, phone for a quick check-in, tablet for review, desktop when you are back at a desk. It is not trying to recreate the old desktop IDE in a browser; it is a control surface for persistent, parallel, human-in-the-loop agent work. +### Is PI WEB a Pi web UI? + +Yes. PI WEB is a Pi web UI for running and supervising Pi Coding Agent sessions from a browser. Unlike simple session viewers, PI WEB is built around persistent server-side workspaces, long-running session daemons, git worktrees, remote machines, and multi-device supervision. + ## Core model PI WEB organizes work into four levels: @@ -69,7 +73,7 @@ This maps naturally to real development work: ## Architecture -PI WEB uses a split-process architecture so agent runtimes are not owned by the browser-facing dev server. +PI WEB uses a split-process architecture so agent runtimes are not owned by the browser-facing dev server. Under the hood, it acts as a browser-based control plane for sessions, workspaces, files, terminals, and trusted remote machines. ```text Browser UI diff --git a/docs/404.html b/docs/404.html index 069a501..2636de0 100644 --- a/docs/404.html +++ b/docs/404.html @@ -6,8 +6,16 @@ Page not found — PI WEB + + - + + + + + + + + + + + + + +
+ +
+ +
+
+
+

Configuration reference

+

Configure PI WEB where your agents work.

+

+ PI WEB configuration covers the machine-local and project-local settings you usually need: bind address, + trusted development-host settings, UI preferences, plugin enablement, file-explorer path access, upload + limits, and session-daemon tools. +

+
+
+ +
+
+ + +
+
+

Config files

+

PI WEB uses a global config file for machine-local settings and a project-local file for repository settings.

+
    +
  • Global config: $PI_WEB_CONFIG, or $XDG_CONFIG_HOME/pi-web/config.json, or ~/.config/pi-web/config.json.
    • +
  • Project config: <project>/.pi-web/config.json for commit-able project settings.
    • +
+

+ Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's + config by opening that machine directly or changing files on that machine. +

+

+ If you installed services with a custom config path, rerun + pi-web install --config /path/to/config.json after changing that path or after upgrading from + a version that only applied the custom path to the web service. This regenerates service files so the + web/API and session daemon use the same PI_WEB_CONFIG. +

+
+ +
+

Precedence and reloads

+

Runtime values are resolved in this order:

+
+ 
defaults → config file → environment overrides
+
+

+ Environment overrides include PI_WEB_HOST, PI_WEB_PORT / PORT, + PI_WEB_ALLOWED_HOSTS, PI_WEB_MAX_UPLOAD_BYTES, PI_WEB_SPAWN_SESSIONS, + and PI_WEB_SUBSESSIONS. +

+
    +
  • host / port: restart the web/API service or process.
    • +
  • maxUploadBytes: restart both the web/API process and the session daemon.
    • +
  • spawnSessions / subsessions: restart the session daemon.
    • +
  • pathAccess: applies on the next request; existing file views may need a browser refresh.
    • +
  • plugins: reload the browser tab after changing plugin enablement.
    • +
  • shortcuts: saved settings apply in the browser after config refresh/save.
    • +
+
+ +
+

Global config example

+

+ pi-web install creates the initial file. You can also save settings from + Settings → General, Settings → Plugins, Settings → Keyboard, + and Settings → Session daemon. +

+
+
+ Example config.json + +
+ 
{
+  "host": "127.0.0.1",
+  "port": 8504,
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  },
+  "maxUploadBytes": 67108864,
+  "spawnSessions": true,
+  "subsessions": false,
+  "plugins": {
+    "workspace-tasks": { "enabled": true },
+    "updates": { "enabled": true },
+    "info": { "enabled": false }
+  },
+  "shortcuts": {
+    "core:view.chat": "mod+1",
+    "core:session.stop": null
+  }
+}
+
+
+ +
+

Project-local config

+

+ Project-local config lives at <project>/.pi-web/config.json. Use it for settings that should + follow a repository. When a project config defines pathAccess, PI WEB merges it after the + global path list. +

+
+
+ .pi-web/config.json + +
+ 
{
+  "version": 1,
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  }
+}
+
+

+ Project-local pathAccess.allowedPaths entries must still be host-absolute or + ~-prefixed; relative roots are not supported. Plugins may own separate project files, such as + .pi-web/tasks.json for the built-in Workspace Tasks plugin. +

+
+ +
+

Config matrix

+

+ Use this table as the quick reference for where a setting can live, which environment variable overrides + it, and whether project-local config overrides or merges with global config. Rows with JSON key + — are runtime-only environment variables, not config-file keys. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConfigJSON keyEnv varScopeProject-local behaviorApplies / restart
Config-file keys
Web/API bind hosthostPI_WEB_HOSTGlobalNot supported locallyRestart web/API
Web/API portportPI_WEB_PORT, PORTGlobalNot supported locallyRestart web/API
Dev-server allowed hostsallowedHostsPI_WEB_ALLOWED_HOSTSGlobalNot supported locallyRestart dev web/UI
External filesystem rootspathAccess.allowedPaths—Global + projectMerges: global roots first, then project roots; duplicates removedNext file request; refresh existing views if needed
Upload/body limitmaxUploadBytesPI_WEB_MAX_UPLOAD_BYTESGlobalNot supported locallyRestart web/API and session daemon
Agent can spawn sessionsspawnSessionsPI_WEB_SPAWN_SESSIONSGlobal/session daemonNot supported locallyRestart session daemon
Tracked subsessions (beta)subsessionsPI_WEB_SUBSESSIONSGlobal/session daemonNot supported locally; also requires spawnSessionsRestart session daemon
Plugin enablement/settingsplugins.<id>.enabled, plugins.<id>.settings—GlobalNot core local config; plugins may read their own project filesReload browser tab
Keyboard shortcutsshortcuts.<actionId>—GlobalNot supported locallyApplies after settings save/config refresh
Project config versionversion—ProjectProject-local only; must be 1 when presentNext project-config read
Runtime-only environment variables
Global config file path—PI_WEB_CONFIG (XDG_CONFIG_HOME affects the default path)Process/envSelects the global config file; not a project configRestart services/processes after changing env
Managed data directory—PI_WEB_DATA_DIRProcess/envNot supported locallyRestart services before changing; moves managed state location
Session daemon socket—PI_WEB_SESSIOND_SOCKETWeb/API + session daemon envNot supported locallyRestart daemon and web/API; both must match
Session daemon TCP port—PI_WEB_SESSIOND_PORTSession daemon envNot supported locallyRestart session daemon; set PI_WEB_SESSIOND_URL for web/API too
Session daemon TCP host—PI_WEB_SESSIOND_HOSTSession daemon envNot supported locallyRestart session daemon
Web-to-daemon URL—PI_WEB_SESSIOND_URLWeb/API envNot supported locallyRestart web/API
Projects storage file—PI_WEB_PROJECTS_FILEWeb/API + session daemon envNot supported locallyRestart services; advanced state override
Remote machines storage file—PI_WEB_MACHINES_FILEWeb/API envNot supported locallyRestart web/API; advanced state override
Pi session storage directory—PI_CODING_AGENT_SESSION_DIRPi/session daemon envNot supported locallyRestart session daemon; follows Pi session priority
Pi agent config directory—PI_CODING_AGENT_DIRPi/Web/API/session daemon envNot supported locallyRestart services
Skip update checks—PI_WEB_SKIP_VERSION_CHECK, PI_WEB_OFFLINE, PI_SKIP_VERSION_CHECK, PI_OFFLINEWeb/API envNot supported locallyRestart web/API after env changes
+
+
+ +
+

External path access

+

+ pathAccess.allowedPaths grants PI WEB's file explorer and absolute @ path + completions access to specific filesystem roots outside the current workspace. By default, + workspace-relative file reads stay inside the workspace and absolute paths are denied. +

+

Accepted root forms:

+
    +
  • Unix absolute paths, for example /opt/reference.
    • +
  • Home-relative paths, for example ~/SDKs.
    • +
  • Windows absolute paths on Windows hosts, for example C:\Users\dev\SDKs.
    • +
+

+ When an absolute request is served, PI WEB expands ~, canonicalizes configured roots with + realpath, requires roots to be existing directories, and rejects symlink escapes outside the + allowed roots. +

+
+ This is not a sandbox for the underlying Pi Coding Agent or your OS user. It only controls PI WEB UI/API + file exposure outside a workspace. Add only roots you trust PI WEB to list and read through the browser UI. +
+
+ +
+

Session daemon tools

+

spawnSessions

+

+ Boolean. Controls whether agents receive the spawn_session tool. Defaults to + true. Set it to false if you do not want an agent to start independent PI WEB sessions. +

+

Environment override: PI_WEB_SPAWN_SESSIONS=0|1|true|false.

+ +

subsessions

+

+ Boolean. Beta. Controls whether agents receive the tracked-subsession tools: + spawn_subsession, list_subsessions, check_subsession, and + read_subsession. Defaults to false and also requires spawnSessions + to be enabled. +

+

+ Tracked subsessions let an agent delegate work to child sessions, get notified when children stop + working, and inspect their transcripts. Restart the session daemon after changing this setting. +

+

Environment override: PI_WEB_SUBSESSIONS=0|1|true|false.

+
+ + +
+

Optional completion tools

+

+ File and path @ completions work without extra tools. If fzf is available on the + PI WEB server's PATH, PI WEB uses it to improve completion filtering and ranking; otherwise it + falls back to built-in ranking. +

+
+ Install guide + Markdown reference +
+
+
+
+
+
+ + + + + diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..d437ca2 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,166 @@ +# PI WEB configuration reference + +PI WEB configuration covers the machine-local and project-local settings you usually need: the web/API bind address, trusted development-host settings, UI preferences, plugin enablement, file-explorer path access, upload limits, and session-daemon tools. + +This file is the markdown reference for agents and package consumers. The website page is . + +## Config files + +PI WEB uses two config files: + +- **Global PI WEB config:** `$PI_WEB_CONFIG`, or `$XDG_CONFIG_HOME/pi-web/config.json`, or `~/.config/pi-web/config.json`. +- **Project-local PI WEB config:** `/.pi-web/config.json` for commit-able project settings. + +Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's config by opening that machine directly or changing files on that machine. + +If you installed services with a custom config path, rerun `pi-web install --config /path/to/config.json` after changing that path or after upgrading from a version that only applied the custom path to the web service. This regenerates service files so the web/API and session daemon use the same `PI_WEB_CONFIG`. + +## Precedence and reloads + +Runtime values are resolved as: + +```text +defaults → config file → environment overrides +``` + +Environment overrides include `PI_WEB_HOST`, `PI_WEB_PORT` / `PORT`, `PI_WEB_ALLOWED_HOSTS`, `PI_WEB_MAX_UPLOAD_BYTES`, `PI_WEB_SPAWN_SESSIONS`, and `PI_WEB_SUBSESSIONS`. + +Process restarts depend on the key: + +- `host` / `port`: restart the web/API service or process. +- `maxUploadBytes`: restart both the web/API process and the session daemon. +- `spawnSessions` / `subsessions`: restart the session daemon. +- `pathAccess`: applies on the next request; existing file views may need a browser refresh. +- `plugins`: reload the browser tab after changing plugin enablement. +- `shortcuts`: saved settings apply in the browser after config refresh/save. + +## Global config example + +```json +{ + "host": "127.0.0.1", + "port": 8504, + "pathAccess": { + "allowedPaths": ["~/SDKs", "/opt/reference"] + }, + "maxUploadBytes": 67108864, + "spawnSessions": true, + "subsessions": false, + "plugins": { + "workspace-tasks": { "enabled": true }, + "updates": { "enabled": true }, + "info": { "enabled": false } + }, + "shortcuts": { + "core:view.chat": "mod+1", + "core:session.stop": null + } +} +``` + +## Project-local config + +Project-local config lives at `/.pi-web/config.json`. Use it for settings that should follow a repository. + +```json +{ + "version": 1, + "pathAccess": { + "allowedPaths": ["~/SDKs", "/opt/reference"] + } +} +``` + +Project-local `pathAccess.allowedPaths` entries are merged after the global list and deduplicated. Paths must still be host-absolute or `~`-prefixed; relative roots are not supported. + +Plugins may own separate project files, such as `.pi-web/tasks.json` for the built-in Workspace Tasks plugin. + +## Configuration matrix + +Rows with JSON key `—` are runtime-only environment variables, not config-file keys. + +| Config | JSON key | Env var | Scope | Project-local behavior | Applies / restart | +| --- | --- | --- | --- | --- | --- | +| **Config-file keys** | | | | | | +| Web/API bind host | `host` | `PI_WEB_HOST` | Global | Not supported locally | Restart web/API | +| Web/API port | `port` | `PI_WEB_PORT`, `PORT` | Global | Not supported locally | Restart web/API | +| Dev-server allowed hosts | `allowedHosts` | `PI_WEB_ALLOWED_HOSTS` | Global | Not supported locally | Restart dev web/UI | +| External filesystem roots | `pathAccess.allowedPaths` | — | Global + project | **Merges**: global roots first, then project roots; duplicates removed | Next file request; refresh existing views if needed | +| Upload/body limit | `maxUploadBytes` | `PI_WEB_MAX_UPLOAD_BYTES` | Global | Not supported locally | Restart web/API and session daemon | +| Agent can spawn sessions | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon | +| Tracked subsessions (beta) | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon | +| Plugin enablement/settings | `plugins..enabled`, `plugins..settings` | — | Global | Not core local config; plugins may read their own project files | Reload browser tab | +| Keyboard shortcuts | `shortcuts.` | — | Global | Not supported locally | Applies after settings save/config refresh | +| Project config version | `version` | — | Project | Project-local only; must be `1` when present | Next project-config read | +| **Runtime-only environment variables** | | | | | | +| Global config file path | — | `PI_WEB_CONFIG` (`XDG_CONFIG_HOME` affects the default path) | Process/env | Selects the global config file; not a project config | Restart services/processes after changing env | +| Managed data directory | — | `PI_WEB_DATA_DIR` | Process/env | Not supported locally | Restart services before changing; moves managed state location | +| Session daemon socket | — | `PI_WEB_SESSIOND_SOCKET` | Web/API + session daemon env | Not supported locally | Restart daemon and web/API; both must match | +| Session daemon TCP port | — | `PI_WEB_SESSIOND_PORT` | Session daemon env | Not supported locally | Restart session daemon; set `PI_WEB_SESSIOND_URL` for web/API too | +| Session daemon TCP host | — | `PI_WEB_SESSIOND_HOST` | Session daemon env | Not supported locally | Restart session daemon | +| Web-to-daemon URL | — | `PI_WEB_SESSIOND_URL` | Web/API env | Not supported locally | Restart web/API | +| Projects storage file | — | `PI_WEB_PROJECTS_FILE` | Web/API + session daemon env | Not supported locally | Restart services; advanced state override | +| Remote machines storage file | — | `PI_WEB_MACHINES_FILE` | Web/API env | Not supported locally | Restart web/API; advanced state override | +| Pi session storage directory | — | `PI_CODING_AGENT_SESSION_DIR` | Pi/session daemon env | Not supported locally | Restart session daemon; follows Pi session priority | +| Pi agent config directory | — | `PI_CODING_AGENT_DIR` | Pi/Web/API/session daemon env | Not supported locally | Restart services | +| Skip update checks | — | `PI_WEB_SKIP_VERSION_CHECK`, `PI_WEB_OFFLINE`, `PI_SKIP_VERSION_CHECK`, `PI_OFFLINE` | Web/API env | Not supported locally | Restart web/API after env changes | + +## Key details + +### External path access + +`pathAccess.allowedPaths` grants PI WEB's file explorer and absolute `@` path completions access to specific filesystem roots outside the current workspace. + +By default, workspace-relative file reads stay inside the workspace and absolute paths are denied. Add only roots you trust PI WEB to list and read through the browser UI. + +Accepted root forms: + +- Unix absolute paths: `/opt/reference` +- Home-relative paths: `~/SDKs` +- Windows absolute paths on Windows hosts: `C:\Users\dev\SDKs` + +When an absolute request is served, PI WEB expands `~`, canonicalizes the configured roots with `realpath`, requires roots to be existing directories, and rejects symlink escapes outside the allowed roots. + +This is not a sandbox for the underlying Pi Coding Agent or your OS user. It only controls PI WEB UI/API file exposure outside a workspace. + +### Session daemon tools + +`spawnSessions` controls whether agents receive the `spawn_session` tool. It defaults to `true`; set it to `false` if you do not want an agent to start independent PI WEB sessions. + +`subsessions` is beta and controls whether agents receive the tracked-subsession tools: `spawn_subsession`, `list_subsessions`, `check_subsession`, and `read_subsession`. It defaults to `false` and also requires `spawnSessions` to be enabled. + +Tracked subsessions let an agent delegate work to child sessions, get notified when children stop working, and inspect their transcripts. + +### Plugin config + +Plugins are enabled by default. Set `plugins..enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` before the browser imports it. + +```json +{ + "plugins": { + "workspace-tasks": { "enabled": true, "settings": {} }, + "updates": { "enabled": false } + } +} +``` + +Reload the browser tab after changing plugin enablement. Already-loaded plugin JavaScript is not unloaded from the current page. + +### Shortcut config + +Shortcut values are keyed by action id. Values are shortcut strings such as `mod+k` or `mod+g p`; `null` disables that action's shortcut. + +```json +{ + "shortcuts": { + "core:view.chat": "mod+1", + "core:session.stop": null + } +} +``` + +Prefer Settings → Keyboard for editing shortcuts interactively. + +## Optional completion tools + +File and path `@` completions work without extra tools. If `fzf` is available on the PI WEB server's `PATH`, PI WEB uses it to improve completion filtering/ranking; otherwise it falls back to built-in ranking. diff --git a/docs/faq.html b/docs/faq.html index 1742a7d..6e30e6d 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -305,6 +306,7 @@ Remote-first Fleet Install + Config Plugins Issues diff --git a/docs/index.html b/docs/index.html index 2fb873b..bfa5fce 100644 --- a/docs/index.html +++ b/docs/index.html @@ -66,6 +66,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -349,6 +350,7 @@ Remote-first Fleet Install + Config Plugins FAQ npm diff --git a/docs/install.html b/docs/install.html index cfddc18..a304eb0 100644 --- a/docs/install.html +++ b/docs/install.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -265,27 +266,33 @@

- Default config + Common config 
{
   "host": "127.0.0.1",
   "port": 8504,
-  "allowedHosts": []
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  },
+  "spawnSessions": true,
+  "subsessions": false
 }

- The web server defaults to 127.0.0.1:8504 and stores PI WEB state in ~/.pi-web. + Use Settings → General for host, port, and external filesystem roots; Settings → Session daemon + for agent-spawn tools; Settings → Plugins for plugin enablement; and Settings → Keyboard + for shortcut overrides. +

+
+ Need the full schema, restart rules, project-local .pi-web/config.json, path access details, and + environment variable reference? Read the configuration reference. +
+

+ The web server defaults to 127.0.0.1:8504, and PI WEB-managed state defaults to + ~/.pi-web. External filesystem paths are denied by default unless listed in + pathAccess.allowedPaths.

-
    -
  • PI_WEB_CONFIG: path to a config JSON file. Defaults to ~/.config/pi-web/config.json.
    • -
  • PI_WEB_PORT or PORT: web server port. Overrides the config file.
    • -
  • PI_WEB_HOST: web server bind host. Overrides the config file. Use 127.0.0.1 for local/tunnel-only access, or a specific VPN/private-network IP for trusted remote access.
    • -
  • PI_WEB_DATA_DIR: data directory, default ~/.pi-web.
    • -
  • PI_WEB_SESSIOND_SOCKET: Unix socket path for daemon communication.
    • -
  • PI_CODING_AGENT_SESSION_DIR: Pi session storage directory. PI WEB follows Pi's priority for sessions: this environment variable, then sessionDir in Pi settings for the selected workspace, then Pi's default session directory.
    • -
  • PI_CODING_AGENT_DIR: Pi agent config directory for auth, settings, resources, and default session storage.
    • -
@@ -334,6 +341,7 @@ Home Remote-first Fleet + Config Plugins FAQ GitHub diff --git a/docs/machines.html b/docs/machines.html index 4d7005e..665f222 100644 --- a/docs/machines.html +++ b/docs/machines.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -289,6 +290,7 @@ PI WEB gateway you opened Home Remote-first Install + Config Plugins FAQ GitHub diff --git a/docs/plugins.html b/docs/plugins.html index 53a2936..8068d5b 100644 --- a/docs/plugins.html +++ b/docs/plugins.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -430,6 +431,7 @@ After editing, check the manifest endpoint and browser-console failure cases.Remote-first Fleet Install + Config FAQ GitHub diff --git a/docs/remote-first.html b/docs/remote-first.html index 4943dce..fd7b5fd 100644 --- a/docs/remote-first.html +++ b/docs/remote-first.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -206,6 +207,7 @@ Home Fleet Install + Config Plugins FAQ GitHub diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 6913ebc..27b7161 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -4,6 +4,7 @@ https://pi-web.dev/remote-first https://pi-web.dev/machines https://pi-web.dev/install + https://pi-web.dev/config https://pi-web.dev/plugins https://pi-web.dev/faq diff --git a/docs/styles.css b/docs/styles.css index 95b99d7..9ea31df 100644 --- a/docs/styles.css +++ b/docs/styles.css @@ -847,6 +847,60 @@ code .comment, font-size: 1.25rem; } +.table-scroll { + overflow-x: auto; + margin: 16px 0; + border: 1px solid var(--line); + background: var(--panel); +} + +.doc-content table { + width: 100%; + min-width: 860px; + border-collapse: collapse; +} + +.doc-content th, +.doc-content td { + padding: 12px 14px; + border-bottom: 1px solid var(--line); + text-align: left; + vertical-align: top; +} + +.doc-content th { + background: var(--panel-strong); + color: var(--text); + font-size: 0.78rem; + letter-spacing: 0.05em; + text-transform: uppercase; +} + +.doc-content .table-section th { + border-top: 2px solid var(--line-bright); + border-bottom-color: var(--line-bright); + background: var(--panel-strong); + color: var(--text); + letter-spacing: 0.08em; +} + +.doc-content td { + color: var(--muted); +} + +.doc-content td:first-child { + color: var(--text); + font-weight: 700; +} + +.doc-content tr:last-child td { + border-bottom: 0; +} + +.doc-content table code { + white-space: nowrap; +} + .code-card { overflow: hidden; margin: 16px 0; diff --git a/package.json b/package.json index ac172e4..d57a16b 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "LICENSE", "extensions", "docs/plugins.md", + "docs/config.md", "docs/assets", "plugin-api.d.ts", "plugin-api/unstable.d.ts" diff --git a/src/cli.ts b/src/cli.ts index d7f9dea..75d2c64 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -386,20 +386,21 @@ function restartOrder(refs: ServiceRef[]): ServiceRef[] { } function productionServiceDefinitions(options: InstallOptions, configPath: string, executables: ServiceExecutables): ServiceDefinition[] { + const environment = configEnvironment(options, configPath); return [ { ...serviceRefs.sessiond, description: "PI WEB session daemon", shellCommand: `exec ${executables.sessiond.command}`, restart: "on-failure", - environment: {}, + environment, }, { ...serviceRefs.web, description: "PI WEB server", shellCommand: `exec ${executables.web.command}`, restart: "on-failure", - environment: configEnvironment(options, configPath), + environment, after: ["sessiond"], wants: ["sessiond"], }, @@ -429,13 +430,14 @@ function validateDevCheckout(root: string): void { } function devServiceDefinitions(options: InstallOptions, configPath: string, root: string): ServiceDefinition[] { + const environment = configEnvironment(options, configPath); return [ { ...serviceRefs.sessiond, description: "PI WEB session daemon (dev)", shellCommand: "exec npm run start:sessiond", restart: "never", - environment: {}, + environment, workingDirectory: root, }, { @@ -443,7 +445,7 @@ function devServiceDefinitions(options: InstallOptions, configPath: string, root description: "PI WEB UI dev server", shellCommand: `exec /usr/bin/env bash -c ${serviceShellQuote('trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait')}`, restart: "never", - environment: configEnvironment(options, configPath), + environment, after: ["sessiond"], wants: ["sessiond"], workingDirectory: root, diff --git a/src/server/sessiond.ts b/src/server/sessiond.ts index 62a17b3..f4cc36e 100644 --- a/src/server/sessiond.ts +++ b/src/server/sessiond.ts @@ -21,13 +21,13 @@ import { getPiWebRuntimeComponent } from "./piWebStatus.js"; import { SESSIOND_RUNTIME_CAPABILITIES } from "../shared/capabilities.js"; import { effectivePiWebConfig, maxUploadBytes, spawnSessionsEnabled, subsessionsEnabled } from "../config.js"; -const app = Fastify({ logger: true, bodyLimit: maxUploadBytes() }); +const { config } = effectivePiWebConfig(); +const app = Fastify({ logger: true, bodyLimit: maxUploadBytes(process.env, config) }); await app.register(fastifyWebsocket); const eventHub = new SessionEventHub(); const workspaceActivity = new WorkspaceActivityService(eventHub); const auth = new AuthService(); -const { config } = effectivePiWebConfig(); const spawnTargets = spawnSessionsEnabled(process.env, config) ? new ProjectScopedSpawnTargetResolver({ projects: new ProjectService(new ProjectStore()), workspaces: new WorkspaceService() }) : undefined; From 2bb6e48a8b7c1f7a8c51a21a498843135162879e Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Tue, 23 Jun 2026 20:03:44 +0200 Subject: [PATCH 30/31] fix: normalize Windows path suggestions --- .changeset/normalize-windows-path-suggestions.md | 5 +++++ src/server/workspaces/fileSuggestions.ts | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 .changeset/normalize-windows-path-suggestions.md diff --git a/.changeset/normalize-windows-path-suggestions.md b/.changeset/normalize-windows-path-suggestions.md new file mode 100644 index 0000000..70b172b --- /dev/null +++ b/.changeset/normalize-windows-path-suggestions.md @@ -0,0 +1,5 @@ +--- +"@jmfederico/pi-web": patch +--- + +Normalize allowed external path suggestions on Windows so configured absolute paths use platform separators consistently. diff --git a/src/server/workspaces/fileSuggestions.ts b/src/server/workspaces/fileSuggestions.ts index 739695e..441babe 100644 --- a/src/server/workspaces/fileSuggestions.ts +++ b/src/server/workspaces/fileSuggestions.ts @@ -206,8 +206,8 @@ function pathSuggestionPrefix(query: string): { directoryPrefix: string; searchP function appendRequestPath(base: string, name: string): string { if (base === "") return name; - if (hasTrailingPathSeparator(base)) return `${base}${name}`; if (isAbsolute(base) || win32.isAbsolute(base)) return join(base, name); + if (hasTrailingPathSeparator(base)) return `${base}${name}`; return `${base}/${name}`; } From bf36df24fd09ae79412750a6b65ad6dd4be8c3dd Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Tue, 23 Jun 2026 21:37:02 +0200 Subject: [PATCH 31/31] chore(release): v1.202606.5 --- .changeset/document-config-reference.md | 5 ----- .changeset/fix-remote-session-reload.md | 5 ----- .changeset/fix-skill-read-duplicates.md | 5 ----- .changeset/fix-subsessions-setting-save.md | 5 ----- .changeset/fix-swedish-dead-key-terminal.md | 5 ----- .changeset/guard-mobile-navigation-focus.md | 5 ----- .changeset/normalize-windows-path-suggestions.md | 5 ----- .changeset/path-access-allowed-roots.md | 5 ----- .changeset/tracked-subsessions.md | 7 ------- CHANGELOG.md | 16 ++++++++++++++++ package-lock.json | 4 ++-- package.json | 2 +- 12 files changed, 19 insertions(+), 50 deletions(-) delete mode 100644 .changeset/document-config-reference.md delete mode 100644 .changeset/fix-remote-session-reload.md delete mode 100644 .changeset/fix-skill-read-duplicates.md delete mode 100644 .changeset/fix-subsessions-setting-save.md delete mode 100644 .changeset/fix-swedish-dead-key-terminal.md delete mode 100644 .changeset/guard-mobile-navigation-focus.md delete mode 100644 .changeset/normalize-windows-path-suggestions.md delete mode 100644 .changeset/path-access-allowed-roots.md delete mode 100644 .changeset/tracked-subsessions.md diff --git a/.changeset/document-config-reference.md b/.changeset/document-config-reference.md deleted file mode 100644 index 93e519f..0000000 --- a/.changeset/document-config-reference.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Add a dedicated PI WEB configuration reference covering config-file precedence, project-local config, external path access allowlists, session daemon tools, plugins, shortcuts, upload limits, and environment variables. Custom `pi-web install --config` paths are now passed to the session daemon service as well as the web service, and the session daemon now honors config-file `maxUploadBytes` values. diff --git a/.changeset/fix-remote-session-reload.md b/.changeset/fix-remote-session-reload.md deleted file mode 100644 index d282e53..0000000 --- a/.changeset/fix-remote-session-reload.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Fix remote session reloads so they proxy through the web/API instead of returning the app shell as JSON. diff --git a/.changeset/fix-skill-read-duplicates.md b/.changeset/fix-skill-read-duplicates.md deleted file mode 100644 index d12accd..0000000 --- a/.changeset/fix-skill-read-duplicates.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Prevent live skill-loading cards from duplicating when the finalized transcript groups multiple skill reads. diff --git a/.changeset/fix-subsessions-setting-save.md b/.changeset/fix-subsessions-setting-save.md deleted file mode 100644 index c1ef89a..0000000 --- a/.changeset/fix-subsessions-setting-save.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Persist the Settings → Session daemon tracked subsessions toggle so it remains enabled after restart. diff --git a/.changeset/fix-swedish-dead-key-terminal.md b/.changeset/fix-swedish-dead-key-terminal.md deleted file mode 100644 index 903057c..0000000 --- a/.changeset/fix-swedish-dead-key-terminal.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Fix dead-key/IME input in the terminal (e.g. typing `~` on a Swedish keyboard). The character previously stuck in the top-left corner and was never sent to the shell. The terminal panel now includes the xterm composition-view styles and no longer forces the helper textarea's position with `!important`, so dead-key composition is placed at the cursor and committed correctly. diff --git a/.changeset/guard-mobile-navigation-focus.md b/.changeset/guard-mobile-navigation-focus.md deleted file mode 100644 index f49868e..0000000 --- a/.changeset/guard-mobile-navigation-focus.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Keep mobile navigation on the selected session when remote workspace loading finishes out of order. diff --git a/.changeset/normalize-windows-path-suggestions.md b/.changeset/normalize-windows-path-suggestions.md deleted file mode 100644 index 70b172b..0000000 --- a/.changeset/normalize-windows-path-suggestions.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Normalize allowed external path suggestions on Windows so configured absolute paths use platform separators consistently. diff --git a/.changeset/path-access-allowed-roots.md b/.changeset/path-access-allowed-roots.md deleted file mode 100644 index ae2fd8f..0000000 --- a/.changeset/path-access-allowed-roots.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Allow configured external filesystem roots to be listed, read, configured from the global settings UI, and completed from absolute `@` path suggestions while keeping absolute paths denied by default, advertise workspace-scoped file suggestion support as a remote-machine capability, and use `fzf` when available to improve file/path completion filtering. diff --git a/.changeset/tracked-subsessions.md b/.changeset/tracked-subsessions.md deleted file mode 100644 index b1012bd..0000000 --- a/.changeset/tracked-subsessions.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"@jmfederico/pi-web": patch ---- - -Add tracked subsessions (beta, off by default): agents can spawn child sessions they stay attached to. The new `spawn_subsession` tool starts a child session linked to its parent (recorded in the session tree), notifies the parent when the child stops working, and lets the parent inspect children via `list_subsessions`, `check_subsession` (a quick glance at a child's status and latest output), and `read_subsession` (read through a child's transcript with role/content filters, full-content substring search, optional per-value `maxChars` truncation that flags clipped parts, and pagination). The completion notice is delivered as a system-authored message (not attributed to the human), and still wakes an idle parent while queueing behind any in-flight work. Unlike the fire-and-forget `spawn_session`, subsessions are observable by their spawner. - -The capability is gated behind a beta flag so it can ship without being exposed in releases: enable it with the `PI_WEB_SUBSESSIONS` env var, the `subsessions` config key, or the "Allow agents to start tracked subsessions" toggle in Settings → Session daemon. It also requires `spawnSessions` to be enabled. Requires a manual session daemon restart to take effect. diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a1e1b8..568c1bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # @jmfederico/pi-web +## 1.202606.5 + +### Patch Changes + +- c2e2a29: Add a dedicated PI WEB configuration reference covering config-file precedence, project-local config, external path access allowlists, session daemon tools, plugins, shortcuts, upload limits, and environment variables. Custom `pi-web install --config` paths are now passed to the session daemon service as well as the web service, and the session daemon now honors config-file `maxUploadBytes` values. +- 4f4c6fa: Fix remote session reloads so they proxy through the web/API instead of returning the app shell as JSON. +- 62c2234: Prevent live skill-loading cards from duplicating when the finalized transcript groups multiple skill reads. +- 27bc924: Persist the Settings → Session daemon tracked subsessions toggle so it remains enabled after restart. +- d931101: Fix dead-key/IME input in the terminal (e.g. typing `~` on a Swedish keyboard). The character previously stuck in the top-left corner and was never sent to the shell. The terminal panel now includes the xterm composition-view styles and no longer forces the helper textarea's position with `!important`, so dead-key composition is placed at the cursor and committed correctly. +- 6933d3a: Keep mobile navigation on the selected session when remote workspace loading finishes out of order. +- 2bb6e48: Normalize allowed external path suggestions on Windows so configured absolute paths use platform separators consistently. +- 9cc20d6: Allow configured external filesystem roots to be listed, read, configured from the global settings UI, and completed from absolute `@` path suggestions while keeping absolute paths denied by default, advertise workspace-scoped file suggestion support as a remote-machine capability, and use `fzf` when available to improve file/path completion filtering. +- 355ebe8: Add tracked subsessions (beta, off by default): agents can spawn child sessions they stay attached to. The new `spawn_subsession` tool starts a child session linked to its parent (recorded in the session tree), notifies the parent when the child stops working, and lets the parent inspect children via `list_subsessions`, `check_subsession` (a quick glance at a child's status and latest output), and `read_subsession` (read through a child's transcript with role/content filters, full-content substring search, optional per-value `maxChars` truncation that flags clipped parts, and pagination). The completion notice is delivered as a system-authored message (not attributed to the human), and still wakes an idle parent while queueing behind any in-flight work. Unlike the fire-and-forget `spawn_session`, subsessions are observable by their spawner. + + The capability is gated behind a beta flag so it can ship without being exposed in releases: enable it with the `PI_WEB_SUBSESSIONS` env var, the `subsessions` config key, or the "Allow agents to start tracked subsessions" toggle in Settings → Session daemon. It also requires `spawnSessions` to be enabled. Requires a manual session daemon restart to take effect. + ## 1.202606.4 ### Patch Changes diff --git a/package-lock.json b/package-lock.json index 3784ed7..27e71d3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@jmfederico/pi-web", - "version": "1.202606.4", + "version": "1.202606.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@jmfederico/pi-web", - "version": "1.202606.4", + "version": "1.202606.5", "license": "MIT", "dependencies": { "@codemirror/commands": "^6.10.3", diff --git a/package.json b/package.json index d57a16b..47e4140 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@jmfederico/pi-web", - "version": "1.202606.4", + "version": "1.202606.5", "description": "Web UI for persistent Pi Coding Agent sessions in real workspaces.", "license": "MIT", "author": "Federico Jaramillo Martinez",