npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@rgaricano/gentle-companion

v0.6.2

Published

Local-first remote control for Gentle Shell sessions: live activity feed, steering, git diff, file drop and phone pairing from a single Rust daemon.

Readme

Gentle Companion

Lightweight, local-first remote control for Gentle Shell sessions.

Fork of pi-companion, adapted for Gentle Shell. This repository lives at IAI-00-IAI/gentle-companion. Leer en español

Watch the Gentle Companion walkthrough (2 min)

Leer en español

Watch the 2-minute narrated walkthrough: a real Gentle Shell session shared with /remote-control, a phone paired from the dashboard, Gentle Shell's questions answered from the phone, and an automation created, triggered and reviewed. It is recorded from the actual terminal and UI and composed in code in tools/promo-video.

New in 0.6.0: the tailcat client is now first-class — the daemon serves the full Companion UI itself, a phone pairs by QR (or a copyable link) and the client prefers the direct LAN path, falling back to the tailcat tunnel (tailcat's WASM client) when the daemon is not reachable that way. The daemon also serves its device surface on a loopback mirror while the tunnel is enabled, because tailcat serve always forwards to loopback. The static page in bridge/ remains as a manual test harness. See bridge/README.md.

In 0.4.3: the companion became a bridge to the computer running Gentle Shell. Links and inline code the agent writes can open localhost servers (http://localhost:3000) in a sandboxed frame relayed by the daemon, and files the agent mentions (paths, file:// links) can be fetched, previewed or downloaded on the device. Every open or fetch asks first; files are limited to the session's working directory and its Companion temp folders; files that look like credentials are skipped (best effort). Turn the whole bridge off in Settings → Bridge. See Companion bridge.

0.3.16: Gentle Shell 1.4.0 compatibility hardening keeps sessions active through startup and automatic retries, safely queues remote prompts during busy runs, and prevents cancelled or truncated automation responses from being reported as successful. Regression coverage now includes overlapping relayed dialogs. Development checks use Gentle Shell 1.4.0. Revamped automation details distinguish manual runs from active/paused schedules and explain failure handling. Agent links and shared reports offer opt-in sandboxed previews without a host-browser controller or URL proxy.

0.3.13: Changes is scoped to session-recorded edits and applied Pi Jar subagent files, with compact mobile review controls. The session menu contains background work with elapsed timers and a scrollable Tasks popup for Pi Jar and compatible extensions. Claymorphism error pages provide safe recovery actions and explain failed page downloads.

0.3.12: Browse Changes one file at a time with a file picker and previous/next controls; the complete file inventory remains visible even when previews are limited. Automations support IANA timezone selection, daylight-saving changes, and the next scheduled run. Pair devices from the terminal with npm run --silent pair. Settings accumulates weekly observed tokens and estimated cost across retained sessions while keeping account-limit snapshots separate.

0.3.11: Changes includes worktree selection, branch and file counts, and new-file previews. Provider usage snapshots survive closed and archived sessions and daemon restarts, with accurate quota labels. Clay background-work badges open shell/subagent lists, and automation phases open scrollable flowcharts with failure and retry paths.

0.3.10: Shell output uses one collapsed full-output section without a duplicate preview, with larger expand/collapse controls. Sessions show compact counts of reported running background shells and active subagents.

0.3.9: Model-written session titles are saved in the session file (keyed by a hash of the prompt, not the prompt itself), so resuming or reloading a session shows the same title without asking the model again.

0.3.8: The session feed is easier to scan: shell calls show a one-line, human summary ("Check git status, Run tests +1 more") instead of the raw script, while output stays intact. Agent thinking renders as Markdown with a live animated state and "Thought for Ns" once done. Unnamed sessions get a short title that summarises the first prompt, inferred by the session's own model while shared, with an instant local fallback.

When a session is shared, Companion fetches OpenAI Codex and Anthropic subscription usage via Gentle Shell's existing OAuth resolver, independently per provider with five-minute caching and failure backoff. Credentials are never sent to the browser or stored by the daemon. API-key accounts and unsupported providers have no built-in subscription lookup; extensions can still publish the neutral telemetry contract. Provider rate-limit, quota and authentication failures are shown in the activity feed with safe remediation guidance rather than raw provider payloads.

Filename search is case-insensitive. New browser uploads are marked You; local agent uploads can declare Agent by posting to /api/sessions/{session_id}/files?source=agent. This query is honored only on the local admin endpoint; remote uploads always remain user uploads. Older files without provenance show Unknown. Source badges describe upload provenance, not file-content authorship.

New in 0.3.2: responsive automation and run-history tables, rounded status chips, matching clay-icon headers, and a single-column automation workspace with full-width mobile controls. Edit automation scrolls to and focuses the inline editor. Pull to refresh Overview, Sessions, Automations, or Settings—with a gesture; unsaved settings stay intact. Camera-policy guidance now explains HTTPS proxy configuration. Existing rich results, staged job editing, optional retries, and answers-only automation sessions are retained. See automations / es-ES.

Gentle Companion is deliberately not another agent runtime. Gentle Shell owns execution and conversation state. A single Rust daemon owns session discovery, pairing, temporary file exchange, browser fan-out, and the embedded web UI.

The UI is a static SvelteKit application. There is no Node runtime in production and no Tauri shell. Rust embeds the generated frontend into the daemon binary.

Gentle Companion overview, dark theme

Screenshots use demo sessions, not private conversation data, and are regenerated with node tools/screenshots.mjs (see Running locally from source). See the session menu, desktop session rows and mobile session list, plus attachment previews, file-grouped changes and connection recovery. Explore the new automation list, summary, run history, job editor, and rich results.

Install

gentle-shell install npm:@rgaricano/gentle-companion

or straight from git:

gentle-shell install git:github.com/IAI-00-IAI/gentle-companion

With Gentle Shell, install the same standard package:

gentle-shell install npm:@rgaricano/gentle-companion

Gentle Shell uses the native package command, so the same pi manifest, extension and skill loading apply. When the extension loads, it checks the local daemon and starts it if needed, downloading the matching sha256-verified release into ~/.pi/agent/pi-companion/bin/<version>/. Daemon startup does not share your session.

Use /remote-control in any session to toggle sharing; /remote-control on and /remote-control off are explicit alternatives. No /companion prerequisite. /companion and /companion off remain compatibility aliases.

You do not need to run gentle-companion-server manually for a normal npm install. Manual daemon startup is mainly for local development, debugging, or when PI_COMPANION_AUTOSTART=0 is set.

Running the daemon yourself

The extension starts the daemon on load: it probes the admin port and launches a daemon only when nothing answers, registering a per-user background service when the platform allows it. Three scripts cover the cases where you want to drive that yourself — they work on Linux, macOS and Windows, need no dependencies, and live in tools/ (they are not shipped in the npm package):

| Script | What it does | | --- | --- | | node tools/daemon.mjs start\|stop\|status\|restart | Manual lifecycle. status probes the admin port and reports running/version/pid; start resolves the binary, launches it detached and waits until it answers; stop sends SIGTERM and waits for the port to close. Add --json for machine-readable output. | | node tools/daemon-service.mjs install\|uninstall\|status | Registers, removes or reports the per-user service: systemd --user on Linux, launchd on macOS, Task Scheduler on Windows. Mirrors what the extension registers, so both paths stay consistent. --binary <path> overrides the binary. | | node tools/daemon-logs.mjs [--lines N] [--follow] | Shows the daemon's log: journalctl --user -u pi-companion.service on Linux, log show/log stream on macOS, and the log file when one exists. Explains what to do when the platform keeps no log. |

The same actions are available through npm run:

npm run daemon:start      npm run daemon:status     npm run daemon:logs
npm run daemon:stop       npm run daemon:restart
npm run daemon:service:install    npm run daemon:service:uninstall    npm run daemon:service:status

Binary resolution order (all three scripts): PI_COMPANION_SERVER → server/target/release/ → server/target/debug/ → the cached download under the companion home → PATH. A normal npm install has no server/target/, so use the cached binary or set PI_COMPANION_SERVER.

The daemon refuses to start twice (it exits when the admin port is taken), so a manual start while the service is running is harmless: it reports that another daemon owns the port.

Architecture

local browser :43721
        |
        v
+---------------------------+
| gentle-companion-server       |
| single Rust daemon        |
|                           |
| live session registry     |
| pairing/device registry   |
| per-session temp sandbox  |
+-------------+-------------+
              |
      localhost WebSocket
    +---------+---------+
    v                   v
Gentle Shell session A        Gentle Shell session B
extension           extension

paired phone
     |
  HTTPS/WSS
     |
tunnel / reverse proxy
     |
     v
remote surface :43722
     |
     +---- same daemon

The local administration surface and paired-device surface are separate listeners. If you expose Gentle Companion through a tunnel, target only port 43722. Never expose port 43721.

For a full architecture reference — process model, HTTP surfaces, auth, every subsystem, the main flows and the operational guides, with diagrams and source anchors — see the knowledge bundle. It is also available in Spanish (es).

Install the web app on your phone

Open the daemon’s HTTPS device URL and pair the phone first. On Android/Chromium, choose Install app (or Add to Home screen) in the browser menu. On iPhone/iPad, open Safari and choose Share → Add to Home Screen; enable Open as Web App if offered. Installation does not grant additional session permissions.

Service workers require HTTPS; http://localhost is permitted for desktop development, but ordinary LAN HTTP addresses are not. An insecure-origin banner explains this in the UI. Install prompts vary by browser and may not appear inside in-app browsers.

After an online visit, the public app shell and visited immutable assets are cached. This is not an offline agent: sending, live activity, pairing, uploads and changes require the daemon connection. No credentials, API responses or session files are stored in the service-worker cache. Reopen online after an update to load the new build.

How the daemon runs

For a normal install:

gentle-shell install npm:@rgaricano/gentle-companion

Start Gentle Shell normally; daemon availability is automatic. Sessions stay private until /remote-control enables sharing. Updating the package and reloading Gentle Shell upgrades the daemon to the matching release; older Gentle Shell processes do not downgrade a newer daemon.

The lifecycle is:

  1. Extension startup probes the daemon and repeats the check every 30 seconds while Gentle Shell is open, without publishing this session.
  2. A process-owned startup lock serializes concurrent sessions, including long downloads. The daemon also refuses duplicate port binds.
  3. Resolve/download and version-check the replacement before stopping the existing daemon. Missing releases or invalid binaries leave the old daemon untouched; there is no latest-release fallback.
  4. When starting a managed daemon, register one per-user background service: macOS launchd, Linux systemd --user, or Windows Task Scheduler. Its supervisor restarts the daemon after crashes and reads the updated binary configuration after upgrades.
  5. If service registration is unavailable (for example no Linux user systemd or insufficient Windows permissions), warn and start a detached daemon instead. Extension-load and periodic checks remain the fallback.
  6. /remote-control toggles only the current session. Session switches reset sharing; turning sharing off never shuts down the daemon.
  7. Upgrades close sockets so browsers and opted-in Gentle Shell sessions reconnect. Active automation runs are stopped during daemon shutdown; the in-memory feed and temporary-file registry do not survive daemon replacement.

Services run with your user privileges, not administrator/root privileges. Login/logout behavior depends on the OS: Linux may need user lingering for logout persistence, and Windows scheduling may be restricted by policy. A pre-existing same-version manual daemon is reused without takeover; service registration happens when Companion needs to start or upgrade it. Package installation alone does not execute a downloader—Gentle Shell must load the extension once.

The daemon binary is resolved in this order:

| Order | Source | |---|---| | 1 | PI_COMPANION_SERVER (explicit path override) | | 2 | a cargo build inside the package checkout: newest of server/target/release and server/target/debug | | 3 | cached download: /bin// | | 4 | gentle-companion-server on PATH | | 5 | download of the GitHub release matching the package version, verified against SHA256SUMS, then cached |

Companion data home

Companion stores its state, settings, pairing registry and daemon cache under a companion home. The home is resolved in this order:

  1. PI_COMPANION_HOME, when set (the full override, unchanged behavior)
  2. <agent home>/pi-companion, where <agent home> comes from:
    • GENTLE_PI_AGENT_HOME, when set (Gentle Shell launcher default)
    • PI_CODING_AGENT_DIR, when set (Gentle Shell agent home)
    • ~/.pi/agent, otherwise

So under Gentle Shell, Companion defaults to <GENTLE_PI_AGENT_HOME>/pi-companion instead of ~/.pi/agent/pi-companion, while PI_COMPANION_HOME always wins. Pairing state, settings, the service folder and the daemon binary cache all follow the same home.

To stop the daemon and remove the OS service, first set PI_COMPANION_SERVICE=0 for Gentle Shell, then disable the per-user service: macOS launchctl bootout gui/$(id -u)/dev.pi-companion.daemon and remove ~/Library/LaunchAgents/dev.pi-companion.daemon.plist; Linux systemctl --user disable --now pi-companion.service and remove ~/.config/systemd/user/pi-companion.service; Windows schtasks /End /TN "Pi Companion" then schtasks /Delete /TN "Pi Companion" /F. Package removal alone does not uninstall an OS service. The supervisor/configuration lives under the daemon home directory's service/ folder.

Optional environment variables (none are required):

| Variable | Effect | |---|---| | PI_COMPANION_SERVER | use this daemon binary | | PI_COMPANION_URL | daemon WebSocket URL (default ws://127.0.0.1:43721); autostart only happens for loopback URLs | | PI_COMPANION_AUTOSTART=0 | disable automatic starts/upgrades and startup monitoring (does not uninstall a previously registered service) | | PI_COMPANION_SERVICE=0 | use detached startup instead of registering a background service (does not uninstall an existing service) | | PI_COMPANION_QUOTAS=0 | disable Companion's OAuth subscription-limit requests | | PI_COMPANION_PUBLIC_URL | daemon-side: public URL embedded in pairing QR codes | | PI_COMPANION_ALLOWED_ORIGINS | daemon-side: extra comma-separated browser origins accepted besides the loopback addresses and the public URL | | PI_COMPANION_ADMIN_ADDR, PI_COMPANION_DEVICE_ADDR | daemon-side: loopback listen addresses (default 127.0.0.1:43721 / 127.0.0.1:43722), for running a second daemon next to the usual one, e.g. for screenshots. The extension still looks for 43721 unless PI_COMPANION_URL points elsewhere | | GENTLE_PI_AGENT_HOME | Companion data home becomes <GENTLE_PI_AGENT_HOME>/pi-companion; Gentle Shell sets this. Overridden by PI_COMPANION_HOME | | PI_CODING_AGENT_DIR | Companion data home becomes <PI_CODING_AGENT_DIR>/pi-companion; Gentle Shell agent home. Overridden by PI_COMPANION_HOME, GENTLE_PI_AGENT_HOME |

Local admin:

http://127.0.0.1:43721

Paired-device surface:

http://127.0.0.1:43722

The remote listener is still loopback-only. Use an authenticated HTTPS tunnel or reverse proxy for access outside the machine.

Set the externally reachable paired-device URL before starting the daemon:

PI_COMPANION_PUBLIC_URL=https://companion.example.com gentle-companion-server

The configured public URL is used to construct pairing invitations and is the browser origin the paired-device surface accepts (see Security boundary).

Per-session remote control

Inside any Gentle Shell session:

/companion          # enable for this session (and print the dashboard address)
/companion off      # stop sharing this session
/remote-control     # toggle sharing on/off

A paired device cannot access sessions that have not explicitly enabled remote control. Turning /remote-control off or running /companion off closes this session’s daemon channel: it disappears from paired devices and becomes Ended on the local dashboard. Gentle Shell continues locally; local Gentle Shell history is untouched. Sharing does not reconnect itself while disabled. /remote-control can enable sharing directly, including on a fresh session; /companion can also resume it. Temporary uploads follow the usual disconnected-session cleanup below.

Questions from Gentle Shell

Gentle Shell's companion_ask_user tool asks one to four questions at once. Each question can offer options with descriptions, allow several choices (multiSelect), and accept a free-text "Other" answer; a question without options is free text. The browser shows them in a bottom sheet within thumb reach; "Later" hides it until you tap the waiting-question badge.

Dialogs from other extensions (ctx.ui.select, ctx.ui.confirm, ctx.ui.input) are relayed to the same sheet while the terminal dialog stays open: whichever side answers first wins and the other closes. Question tools that draw their own ctx.ui.custom picker can use a native-sheet adapter: pi-jar's jar_ask is supported, and a companion answer completes its terminal picker. Standard dialogs work for any extension, not just jar_ask. Pending questions are part of the session snapshot, so a browser that connects later still sees them.

Other ctx.ui.custom components are mirrored in a terminal-style popup, including custom slash-command screens. ANSI colors and selection highlighting are preserved inside a clay-styled, vertically and horizontally scrollable viewer. Text-size controls and view-scroll buttons make long or wide screens easier to read; separate navigation controls and expandable extra keys operate the original component. The input bar stays available while the popup body scrolls, and unsent text is retained if the connection drops. Enter submits according to the extension's keybindings; Close sends Escape so the component supplies its own cancellation result. Components that ignore Escape may remain open. Local completion closes the companion view, and pending frames survive browser reconnects. Ending sharing stops mirroring without closing the local component.

Custom popups use the local terminal's rendered width (scroll horizontally on narrow screens), not an independently resized terminal. Mouse-only interactions, terminal images, and direct terminal I/O are not mirrored. RPC automation sessions cannot mirror custom terminal components because Gentle Shell does not create them in RPC mode. ctx.ui.editor remains terminal-only.

Refreshing your workspace

On Overview, Sessions, and Automations, pull down from the top of the page and release when prompted to refresh current data without reloading the app. Gestures inside inputs and nested scrollable lists are left alone. Settings does not use pull-to-refresh.

The Sessions, Devices, and Settings pages now share the automation page’s clay-icon header style. See device management, settings, and mobile settings.

Notifications, camera and catching up

Settings → Notifications and camera (on every device, not just the console) asks the browser for both permissions from a tap, as browsers require, and shows whether each is allowed, blocked or unavailable. Overview also offers a one-time "Turn on notifications" banner.

With notifications on, the device gets a system notification (through the service worker, so it works for installed apps and Android) when Gentle Shell asks a question, finishes a turn or a session ends. Tapping it opens that session. Nothing is sent while you are already looking at that session. iPhone and iPad only allow web notifications from an app added to the Home Screen. The camera is used only for the pairing QR scanner. Camera access requires HTTPS or localhost; plain HTTP LAN/phone links cannot prompt. After upgrading, restart the daemon and reload the app to refresh cached camera policies. Settings distinguishes browser denial, page/proxy policy blocks and transient camera errors, with retry or manual-code pairing guidance.

Activity no longer lives only in the open tab. The daemon keeps a bounded, in-memory log of each session's recent feed (streamed text is merged, up to 800 entries) at GET /api/sessions/{id}/activity on both surfaces (paired devices: shared sessions only). The UI rebuilds the feed from it when a session opens and after every reconnect or resync, so a phone that slept, dropped its connection or was closed catches up without sending a new message. Prompts, steers and answers from any device are added to that log too. The log is cleared when the daemon restarts or the session is archived.

Attaching files uses plain HTTP, so it keeps working while the live socket is reconnecting (common right after a phone's file picker closes); only a deliberate disconnect or revoked access blocks it.

Pairing and devices

For a terminal-only host, run npm run --silent pair from the Companion package directory (daemon must already be running). It prints a unique single-use pairing code, a pairing link, and the expiry time without opening a browser. Open the link on the device, or enter the code on its Pair page. Treat the printed invitation as a secret; it uses the same expiry, revocation, and device permissions as browser-created invitations. PI_COMPANION_URL may override the local admin address; remote admin targets are refused.

Pairing is daemon-wide rather than session-specific. Everything lives on the Devices page of the local console (port 43721):

  1. Choose Pair a device. The daemon creates a single-use invitation (5 minutes by default, configurable in Settings) and shows it as a QR code, a copyable link and a short code (XXXX-XXXX).
  2. On the phone, open the paired-device address. An unpaired device gets a connect screen: scan the QR code with the in-app camera (HTTPS required), use the phone's camera app to open the invitation link, or type the short code shown beside the QR, then give the device a name. Gentle Companion explains why camera access is needed before triggering the browser permission prompt.
  3. The daemon issues a long random credential and stores only its SHA-256 hash.

Typed codes are short, so wrong ones are counted: after ten misses within ten minutes every open invitation is withdrawn and code entry is refused (HTTP 429) until the window passes.

Each paired device shows a live Connected / Disconnected status (with the number of open tabs), when it was last seen and when it was paired. From the console you can:

  • Disconnect: end the device's live connections (WebSocket close code 4001). It stays paired and can reconnect when its user chooses.
  • Revoke: delete its credential and drop its connections (close code 4003). The device clears its stored credential and must scan a new code.

Paired devices (name, browser user agent, pairing and last-seen times, credential hash) and settings survive daemon restarts. They are stored in ~/.pi/agent/pi-companion/state.json, created with mode 0600 inside a 0700 directory and replaced atomically; a looser mode found on startup is tightened. Override the directory with PI_COMPANION_HOME.

A phone pairs once with the daemon. Individual Gentle Shell sessions opt in using /remote-control. This choice is saved in Gentle Shell session history: resuming that same session restores sharing unless you used /remote-control off. New sessions and forks do not inherit another session's opt-in. After upgrading from 0.3.6 or earlier, enable sharing once to save this choice; older versions did not record it.

Network loss and daemon restarts reconnect automatically with bounded backoff. Heartbeats detect silent connections, and returning to the foreground or restoring network access retries immediately. Pairing credentials and unsent drafts survive outages; session snapshots, pending questions, and previously loaded upload lists refresh on reconnect. Recent activity is replayed from the daemon’s bounded log, but prompts/answers are never automatically resent. A deliberate Disconnect waits for the device’s explicit retry; Revoke removes access and requires pairing again.

Tailcat tunnel

Experimental: the tailcat tunnel is experimental and still under development. It is included behind the Settings → Tunnel toggle, but the client side is not finished; use it at your own risk.

If your workspace has no public IP, enable Settings → Tunnel to let the daemon run a Tailcat tunnel. The daemon exposes the device surface through a tailcat address (tc…) relayed via DERP, so devices can connect without a public IP or inbound ports.

When enabled, the daemon:

  • Starts tailcat serve --json <port> as a child process, using the bundled Tailcat binary when no local one is found.
  • Reads the tailcat address from the server’s stdout JSON ({"listenAddr":"tc..."}) and stores it.
  • Shows the address in Settings → Tunnel, with a copy button and a QR code, plus a live status indicator: green when the tunnel process is running, amber while it is starting, red with the daemon’s error when it fails (for example a missing binary), and grey when disabled.
  • Restarts the tunnel when the daemon restarts while the setting is enabled.
  • Stops the tunnel process and clears the stored address when the tunnel is disabled.

The exposed port is the Tunnel port setting. Leave it at 0 to use the daemon device port (PI_COMPANION_DEVICE_ADDR, default 127.0.0.1:43722); changing the port while the tunnel is enabled restarts the tunnel. The tunnel does not change the Companion admin port.

The tailcat address is sensitive. Treat it like a pairing code: it grants access through the tunnel, so do not share it publicly or commit it to a repository.

The daemon itself serves a first-class browser client: opening the daemon's URL in a phone browser loads the full Companion UI. The client prefers a direct LAN connection and falls back to the tunnel only when the daemon is not reachable that way, so a phone on the same network stays fast and a phone away from it keeps working. Pairing delivers the tunnel address and device port: the claim response carries them, and the pairing QR also encodes them in the URL fragment (never sent to the server), so a phone scanning it lands already configured; for clients without a camera, the devices page shows a copyable pairing link that carries the same configuration. The static page in bridge/ remains as a manual test harness for the tailcat WASM transport, and the address can also be used from tailcat clients such as OpenTailcat or pi-remote.

How the client chooses its path:

  • On the daemon's network: a direct connection. Fast, no relay involved.
  • Away from it: the tailcat tunnel, dialed through the public DERP relay. The switch is automatic — the client re-evaluates the path after a connection failure, so a phone that leaves the network keeps working and one that returns goes back to the direct path.

Known limitations of this release:

  • Do not reload the page while off the network. The client is served over plain HTTP from the daemon's LAN address, so the page itself cannot be fetched without that network. The live session survives losing the network (the tunnel takes over), but a reload does not. Serving the client over HTTPS — which enables a service worker and an installable app — is the next step.
  • Binary transfers over the tunnel are not supported yet. File uploads and downloads report a clear error in tunnel mode; they work normally on the direct path.
  • The tunnel address is a credential. Anyone holding it can reach the device surface through the relay, subject to the pairing token. Treat it like a pairing code.

Serving the client over HTTPS

The client is served over plain HTTP today, which is why a reload off the network fails. Two ways to fix that, either one sufficient:

Option A — TLS on the daemon. Put the daemon behind HTTPS (a reverse proxy with a certificate, or TLS termination in front of the device surface). The client then runs in a secure context, so a service worker can cache the app shell and the tailcat runtime, and the client becomes installable as an app. This keeps everything on the daemon. The certificate must be valid for the host the phone opens — a self-signed certificate on a bare IP address will be rejected by browsers and blocks service-worker registration, so use a real hostname and a trusted certificate.

Option B — host the client on a public static site. Publish the built UI (server/web-dist/) together with bridge/vendor/ to any HTTPS static host (GitHub Pages, Netlify, Cloudflare Pages, an object store with a CDN). The phone then opens that public URL with the tunnel configuration in the fragment, e.g. https://example.com/companion/#tunnel=tc…&port=43722, and never needs the daemon's network to load the app. Requirements:

  • The daemon must accept that origin. Add it to PI_COMPANION_ALLOWED_ORIGINS (comma-separated), or the WebSocket and the API will answer 403 Origin not allowed.
  • The tunnel must be running and its address reachable from the phone, since every request travels through it.
  • The published build must be refreshed when the daemon's UI changes; the two are versioned separately.
  • The page's own assets are public — never place tokens or addresses in the published files, only in the URL fragment, which browsers do not send to servers.

Option B needs no server-side change and no certificate management, at the cost of hosting the client separately from the daemon.

The daemon looks for tailcat in this order: the system PATH, a local binary named tailcat in the current directory or bin/, and then the bundled binary for the current platform. Bundled Tailcat binaries ship for Linux (server/vendor/tailcat/tailcat-amd64, tailcat-arm64, tailcat-armv7) and Windows (tailcat-win-amd64.exe, tailcat-win-arm64.exe); on macOS the daemon uses the system tailcat from PATH. If no binary is found, the daemon shows a per-platform install hint and does not crash:

  • macOS: brew install tailcat (recommended), or go install github.com/tailscale/tailcat/cmd/tailcat@latest, nix profile install nixpkgs#tailcat, nix run github:tailscale/tailcat, or pixi global install tailcat.
  • Linux/Windows: install a release from https://github.com/tailscale/tailcat/releases and put it on PATH to use a different version than the bundled one.

The tunnel uses Tailcat, which is licensed under the BSD 3-Clause License (see THIRD-PARTY-LICENSES.md).

Session metadata and usage

Shared session title, model, effort and working directory refresh on Gentle Shell events and once per second while sharing, including while idle. Session detail shows context-window usage and estimated session cost. Native Gentle Shell context and recorded usage costs take precedence; independent extension reports fill unavailable fields. Missing usage is shown as unavailable, not zero.

Settings → Usage is available on the console and paired devices. It displays the latest snapshot per provider: weekly usage, 5-hour usage when reported, reset times, source and snapshot age. Quota snapshots are not added across sessions or accounts. Those limits are extension-reported, not billing totals or locally inferred quotas. Companion additionally accumulates observed token consumption and estimated cost by provider across retained sessions for the current week (Monday 00:00 UTC). The daemon persists per-session counters and adds only new consumption, avoiding duplicate counts on reconnect or restart; live updates refresh Settings without reloading. The initial saved report includes the session’s known totals, and retention is bounded to 500 sessions, so these estimates are not a complete account-wide bill. Quota freshness and consumption timestamps remain independent. When no quota adapter is installed, 5-hour and weekly quotas still show as unavailable rather than fabricated percentages.

Extensions can publish a provider-neutral event without importing Companion:

pi.events.emit("companion:telemetry", {
  source: "my-usage-extension", // distinguish independent producers
  // sessionId: ctx.sessionManager.getSessionId(), // optional session guard
  context: { tokens: 24000, window: 200000, percent: 12 },
  cost: { amount: 0.25, currency: "USD" },
  providers: [{
    provider: "openai-codex", updatedAt: new Date().toISOString(),
    weekly: { usedPercent: 35, resetsAt: "2026-10-12T00:00:00Z" },
    fiveHour: { usedPercent: 20 } // omit windows the provider doesn't supply
  }]
});

Publish complete snapshots per provider; session context and cost may be supplied independently by different extensions. Companion also accepts usage:update, session:usage and provider:usage with this shape. On opt-in and every 30 seconds it emits companion:telemetry:request with the Gentle Shell sessionId and companionSessionId, allowing adapters to respond with their cached snapshots. It never reads provider credentials or calls quota APIs itself. Extensions with private, non-exported quota data need an adapter to publish this contract.

As a legacy fallback, ctx.ui.setStatus reports with explicit ctx 12% / context 12% and cost: $0.25 (or cost/usage/footer keys containing $0.25) are recognized. Quota status lines must identify provider=… and label 7d/weekly and 5h/5-hour percentages (used, left, or remaining). Unlabelled percentages mean used. Status rendering is preserved. Invalid reports are ignored; extension context/cost expires after five minutes without a fresh reading. Context estimates are also invalidated on model changes, compaction and tree navigation; quota snapshots retain their original timestamps and visibly age.

Settings

The Settings → General page provides appearance and device permissions on every device; daemon configuration is local-console-only:

| Setting | Default | Notes | |---|---|---| | Theme | System | Light, dark or follow the OS. Stored per browser. | | Public address | empty | The tunnel / reverse-proxy URL embedded in pairing codes. PI_COMPANION_PUBLIC_URL overrides it and locks the field. | | Pairing code lifetime | 5 minutes | 1 to 60. | | Largest file | 25 MB | 1 to 100 MB per upload. | | Allowed file types | any | Optional MIME allowlist such as image/*, application/pdf. Uploads outside it get HTTP 415. | | Bridge | on | Lets devices open agent-mentioned localhost servers and fetch agent-mentioned files after a prompt. Off also ends open bridge links. |

It also shows the daemon version, both addresses, and where settings and session files are stored.

Temporary files

Each session has an isolated temporary directory beneath the operating system temp directory:

<temp>/pi-companion/<session-id>/

On Unix the daemon attempts to set the Gentle Companion and session directories to mode 0700.

The browser can upload a file using the composer’s attachment button, or from Shared files in the session menu. Composer attachments show previews, file names, sizes and upload status; validation and upload failures appear beside the file. Image thumbnails are limited to safe raster image types. Removing a preview removes that attachment from the draft; deleting a shared upload remains an explicit action. The current daemon upload policy is checked before selection is uploaded, and the daemon remains authoritative. Current constraints:

  • 25 MiB maximum per upload by default (Settings); a rejected or interrupted upload leaves no partial file
  • optional MIME allowlist: the type guessed from the file name and any specific declared Content-Type must both be allowed
  • session ids in paths are limited to [A-Za-z0-9_-], so they can never name a directory outside the sandbox
  • filename is reduced to its final path component
  • generated opaque file id prefixes the on-disk name
  • the daemon never accepts a client-provided destination path
  • file deletion accepts only the opaque file id
  • deletion verifies the stored path is still inside that session sandbox
  • sandbox content is removed 30 seconds after a disconnected session fails to reconnect

The Gentle Shell extension exposes:

companion_temp_files

which returns the sandbox file paths available to the agent, and:

companion_delete_temp_file

which destroys one temporary file by opaque id.

This means the agent can consume uploaded artifacts using its normal file capabilities while Gentle Companion retains ownership of upload placement and cleanup.

Preview agent links and shared files

Select a link in an agent reply or formatted automation output to open Companion's preview dialog. Public HTTPS links first show the destination; choose Load website preview to contact that site from your current browser. Websites that block embedding require Open in new tab. Plain http:// sites, IP-address URLs and other non-localhost addresses are not proxied; use Open in new tab. Localhost servers and local files use the Companion bridge.

In Shared files, choose Preview for a registered upload. Files up to 2 MiB can display as safe raster images, escaped text or a static HTML snapshot. HTML scripts, navigation and external assets are disabled; JavaScript-dependent pages need the original file outside Companion. Unsupported or larger files remain downloadable.

To share a generated local report, the agent must first upload the chosen file through the existing local-admin upload API (POST /api/sessions/{session_id}/files?source=agent, multipart field file). The agent can then link its unique shared filename, returned sandbox path or session download URL. Companion resolves these references to an existing opaque file id. A path that is not an upload can only be fetched through the confirmed bridge. Previewing does not launch, stream or control the host browser. See Security model for isolation and privacy limits.

Companion bridge

The device can act on what the agent mentions, without any tunnel changes. Links in a reply, and inline code that unmistakably names a file or a localhost server (underlined when actionable), open a prompt first. Nothing is fetched or relayed until you confirm.

| The agent mentions | You confirm | What happens | |---|---|---| | http://localhost:3000 (also 127.0.0.1, [::1], 0.0.0.0) | Open server | The daemon mints an unguessable link that lives on a five-minute lease (an open preview renews it every minute) and relays /bridge/<token>/... to that loopback server. It opens in a sandboxed frame; closing the preview ends the link (Open in new tab only works while it is open). | | /work/app/out/report.html, ~/notes.md, docs/guide.md, file:///... | Fetch and preview or Fetch and download | The daemon copies the file into the session's shared files (as an Agent upload). The usual preview and download controls take over. Fetching again refreshes the copy. |

Limits, all enforced by the daemon, not the UI:

  • Servers: http:// on loopback only, the exact address (port included) must appear in the session's agent output, and Companion's own ports (43721/43722 or their overrides) are never bridged. Closing the preview, turning the bridge off, unsharing the session, archiving it, revoking the device or Pi stopping ends links for good, including responses already streaming; they are never revived. While Pi is disconnected nothing is bridged. If a close cannot reach the daemon (offline), it is retried and the link still lapses with its lease.
  • Each preview gets its own link, so two previews of one server never share it (16 per device per session). Relays are capped at 32 at once; streamed responses at 100 MiB, five minutes and 60 idle seconds; pages that are rewritten must arrive within 30 seconds (10 idle) or fail with 504.
  • Files: the path (symlinks resolved) must be inside the session's working directory, that session's own Companion temp folder, or <temp>/pi-companion/.shared. Other sessions' folders are never reachable. It must appear in the session's agent output as a whole path (report.html.bak does not vouch for report.html), be a regular file within the upload limit and MIME allowlist, and must not look like credentials (.env*, .git, .ssh, .aws, *.pem, secrets.json, .git-credentials, Companion's own state, and similar). Filename rules are a best-effort safety net, not a guarantee; the confirmation prompt is the real control. A session that reports no usable working directory cannot fetch files. What you typed into a prompt cannot vouch for a path or server. Paths with spaces work when written plainly or percent-encoded.
  • Proxied pages run in an opaque origin: no cookies are relayed and WebSockets are not proxied. Root-relative URLs and absolute URLs to the bridged port (http://localhost:3000/app.js in src/href/url()/@import) are rewritten in HTML, CSS and JS; fetch/Request, XHR, EventSource and sendBeacon are redirected at runtime. This is best effort (srcset and URLs built in script are not covered). WebSockets (including HMR sockets) and Web Workers are not supported: the sandboxed frame has an opaque origin, so hot-reload dev servers may render but not live-update.
  • Automation sessions cannot use the bridge.

See Security model.

Camera access through Cloudflare or another HTTPS proxy

Camera scanning works through an HTTPS tunnel; Companion serves Permissions-Policy: camera=(self). A proxy response-header rule that replaces it with camera=() blocks the camera before the browser can ask permission. JavaScript cannot override that restriction.

For a Cloudflare Modify Response Header rule scoped to your Companion hostname (for example, http.host eq "companion.readynaz.com"), set Permissions-Policy to:

geolocation=(), camera=(self), microphone=(), payment=(), usb=(), accelerometer=(), gyroscope=(), magnetometer=()

Exclude the Companion hostname from any broader rule that still sets camera=(), and check Workers or other proxies for duplicate overrides. Keep Cloudflare Access authentication enabled and tunnel only the paired-device listener. Open Companion directly, not inside an iframe. After signing in, verify the final page response in browser DevTools → Network: its camera directive must be camera=(self). The Access login redirect is not the app response. Reload the app (and restart an older daemon after upgrading), then allow Camera in browser site permissions. Manual pairing-code entry remains available.

Workspace and tunnel connection errors

If a tunnel closes, the workspace stops, or your device loses its network, Companion shows an actionable Workspace connection interrupted notice with Retry now and reconnect instructions. On initial connection failure, it shows Workspace unavailable, not a misleading empty session list or “session not found.” Gateway errors (including HTTP 502/503/504 and tunnel-provider errors) are translated into readable messages rather than raw HTML or JSON parse errors. A browser cannot always distinguish a closed tunnel from a daemon, DNS or network failure, so these messages describe possible causes rather than claiming certainty.

  • Ordinary API requests and live-connection handshakes time out after 10 seconds; uploads allow 60 seconds.
  • Reconnection uses bounded backoff and retries when the device returns online. Retry now is available immediately.
  • Previously loaded activity may be stale. Failed sends keep your draft; messages and uploads are never automatically resent.
  • Network/tunnel errors preserve pairing. Explicit computer disconnects still require manual reconnect; revoked credentials still require pairing again.
  • Restart the tunnel, keep the workspace running, and run /companion in Gentle Shell if the daemon is not running. If the tunnel URL changed, open the new HTTPS device URL; a different hostname/origin may require pairing again in that browser.

A previously cached PWA shell can also explain gateway failures on reload. If the app has never loaded successfully on that device and no shell is cached, the browser/tunnel provider owns the initial error page; Companion cannot display its own UI until its assets are reachable.

Session identity

Companion uses Gentle Shell's persistent session ID, so restarting, resuming, or re-enabling sharing replaces the same dashboard entry instead of creating a duplicate. Unnamed sessions use the first text-bearing user prompt in the current branch as their title (whitespace-normalized and capped at 120 characters), with the project folder as a fallback before a prompt exists. /name overrides that title and updates the dashboard live; clearing the name restores the prompt-derived title.

Every registered Gentle Shell session publishes a compact display model to the daemon:

  • session name
  • short title
  • status: active, idle, or stopped
  • main model
  • thinking effort
  • working directory and process id
  • remote-control state

Stopped sessions remain visible in the daemon registry so the dashboard does not lose context when a Gentle Shell process exits. Their controls are disabled and their temporary sandbox is cleaned after the reconnect grace period. Use Archive session on the list or in the session menu to remove a disconnected/stopped entry. The daemon rejects removal of active, idle, waiting, or otherwise connected sessions. Archiving removes only the daemon entry; it never deletes Gentle Shell history, project files or other files on disk. Temporary uploads still follow the existing disconnect cleanup lifecycle. Reopening a previously shared Gentle Shell session registers it again automatically; otherwise use /companion. Entries created by older versions with random IDs can be archived once disconnected.

UI

A single-page SvelteKit app, embedded in the daemon binary:

| Page | Who sees it | What it is for | |---|---|---| | Overview | everyone | Dot-field hero, live counts, sessions that need your answer, a labeled live-session table, and a spaced onboarding/help panel with Claymorphism actions | | Sessions | everyone | Searchable, filterable full-width session rows (Working / Waiting / Ended); the whole row opens the session, the status badge sits top-right, and ended sessions offer a safe Archive action. Paired devices only see shared sessions | | Session detail | everyone | Activity-first transcript with Markdown, highlighted code, Mermaid diagrams, collapsible tool output/thinking and question sheets. Compact header and navigation leave more space for the shell. The expanding composer includes Auto/Plan selection, attachment previews and a full-width labeled Send/Steer action; Plan uses the existing /plan command, not an agent permission setting. The top-right session menu opens Shared files, Changes and Archive session. The session header shows a status dot; clicking its title reveals status and session metadata. Changes offers worktree selection, staged/unstaged counts, a filename filter, and a file picker with previous/next navigation. Files without previews remain listed; selecting a file resets patch scrolling | | Devices | local console only | Pairing, connection status, disconnect and revoke | | Settings | everyone | Theme, notification and camera permissions; on the console also daemon settings with a save bar that appears only for unsaved edits | | Help, Privacy, Terms | everyone | Setup stepper, commands, tools, troubleshooting; data handling; terms of use. Help is opened from the Overview |

The Live indicator in the header and sidebar opens the connection sheet (status, version and, on this computer, the console and device addresses and data folders).

Changes shows dirty files with successful file-operation records in that session, including Pi Jar subagent files explicitly applied to the parent checkout—not every dirty file in the repository. Worktree selection, filtering and attribution warnings are under Options so the patch has room on mobile. Shell-only edits or delegates without an applied-file report may be missing, and a shared file’s patch can contain other sessions’ hunks. Reload the Gentle Shell extension to enable this scope in an existing session.

The session’s three-dot menu opens Background work (shells and subagents with live elapsed time) and Tasks (a scrollable checklist with statuses and subtasks). Elapsed time uses the source start timestamp when available, otherwise the first active report; it freezes while disconnected. Older extensions without timestamps show “Time unavailable.”

Pi Jar tasks are restored from complete task events on the active session branch, including lists larger than its tool-result preview. Other task extensions can publish complete snapshots without importing Companion:

pi.events.emit('companion:tasks', {
  sessionId: ctx.sessionManager.getSessionId(), // guards against late reports from another session
  items: [
    { id: 'review', title: 'Review changes', status: 'in_progress', activeForm: 'Reviewing changes' },
    { id: 'tests', title: 'Run tests', status: 'pending' }
  ]
});

Statuses are pending, in_progress or completed. Use at most 50 items, short alphanumeric/hyphen IDs, and one subtask level with parents listed first. Optional details supplies context; { items: [] } clears the list. Snapshots are saved on the active branch; malformed snapshots and mismatched session IDs are ignored. Arbitrary todo-tool output is not interpreted as a complete task list.

Git problems in the Changes panel (for example a folder that is not a git repository) show as a toast, never in the transcript.

Design notes:

  • light and dark themes with a system default, applied before first paint so there is no flash
  • claymorphism: solid surfaces with an outer drop shadow plus inset highlight and shade (no blur or glass); small icons are Lucide line icons on raised clay wells, feature art is 3D clay renders from 3dicons (CC0)
  • warm amber on graphite or paper, matching the logo; system fonts only, so nothing loads from the network. highlight.js and Mermaid load only when a reply contains code or a diagram
  • the window never scrolls. The sidebar, page content, activity feed, file list, diff, chips and tabs each scroll inside their own container, and the composer and mobile tab bar stay put
  • the shell gently breathes while the displayed session is working, with a slower thinking animation and a soft progress sweep on the mobile header; it stops when idle or disconnected and respects reduced-motion preferences
  • the activity feed follows new output and stops following when you scroll up ("Jump to latest" brings you back)
  • installable PWA: scoped manifest with explicit 192×192 and 512×512 PNG icons plus a maskable icon, standalone display mode, Apple home-screen metadata, and a service worker that caches only the public shell and static assets; API/session traffic and uploads are never cached
  • mobile: bottom tab bar, safe-area insets, 44px touch targets, 16px inputs (no iOS zoom), Enter inserts a newline on touch keyboards
  • accessibility: skip link, visible focus rings, labeled controls and table metadata, accessible session menus, live regions for the feed and questions, reduced-motion support
  • the dot field is Raksara's component, loaded when the browser is idle, paused when hidden, and static under reduced motion. It opens on the Gentle Companion mark, then morphs through a computer, a phone and a terminal
  • dropping a file anywhere outside the Shared files drop zone is ignored. Without this, the browser tries to open the file itself (Firefox reports this as "may not load or link to file:///")

Caching and updates

The UI is built with adapter-static in SPA mode (200.html fallback) and embedded with rust-embed:

  • /_app/immutable/** is content-hashed and served with Cache-Control: public, max-age=31536000, immutable
  • the shell, version.json and icons are served with no-cache and a strong ETag, so a reload costs a 304 until something changes
  • unknown file-like paths return 404 instead of the HTML shell, so a stale tab never parses HTML as JavaScript
  • the app polls version.json every minute; when a new build is detected it shows a reload banner and the next navigation loads the new version
  • HTML responses carry a same-origin Content-Security-Policy and X-Frame-Options: DENY

Generated server/web-dist files are not committed. CI builds them once and every native build embeds the same bundle.

Browser controls

The initial slice supports:

  • multiple live Gentle Shell sessions
  • prompt
  • steer
  • abort
  • /plan
  • git diff
  • streamed lifecycle/tool/message events
  • companion ask-user requests
  • temporary file upload/list/delete
  • paired-device management
  • per-session remote-control opt-in

There is deliberately no arbitrary shell, arbitrary tool invocation, or arbitrary filesystem API.

Running locally from source

Use this only when developing Gentle Companion itself. A published install does not require these steps.

Requirements: Node 22.19+ (matching Gentle Shell 1.4.0) and stable Rust.

Clone the repository, then:

npm install
npm run serve

npm run serve builds the embedded Svelte UI and starts the Rust daemon in the foreground. It prints:

  Gentle Companion v0.3.16

  Console          http://127.0.0.1:43721
  Paired devices   http://127.0.0.1:43722
  Pairing links    http://127.0.0.1:43722  (default, this computer only; set one in Settings)
  Data             ~/.pi/agent/pi-companion  (0 paired)

If a daemon is already running (for example one a Gentle Shell session started automatically), npm run serve prints its console address and exits instead of starting a second copy. Stop the running one first (pkill -f gentle-companion-server) if you want your fresh build to take over. Set RUST_LOG (for example RUST_LOG=debug) for more detailed logs.

Type checks cover the extension (tsc) and the UI (svelte-check, warnings fail):

npm run check

Tests cover the question relay, deferred per-session startup and remote-off/re-enable behavior (including an executable extension/bridge harness), attachment validation and path references, changed-file grouping/filtering, workspace error classification and actual connection-store recovery, install icon dimensions and service-worker cache isolation (node --test), plus the daemon's wire protocol, safe session archiving, pairing expiry and code throttling, origin policy, bridge and device reconnects, path traversal, upload limits, MIME allowlist, state-file permissions and multi-session isolation (cargo test):

npm test

Optional browser regressions run with npm run test:previews. Like the screenshot generator, this requires Playwright with Chromium (or PLAYWRIGHT pointing to its module and CHROME to a browser executable). The script uses isolated state and mock external pages to check mobile/desktop automation layouts, malicious HTML isolation, website consent, paired-device credentials/revocation, stale link requests and focus restoration. It does not use real conversations or contact the preview websites.

UI modules import shared code through the #lib/* subpath import declared in ui/package.json (SvelteKit 3 replaced $lib). Subpath imports do not guess extensions, so always write the full file name: #lib/format.ts, #lib/companion.svelte.ts, #lib/Icon.svelte. ui/tsconfig.json extends SvelteKit's generated $app/tsconfig.

Then, in another shell, start Gentle Shell with the extension from this checkout:

gentle-shell -e ./src/index.ts

After you run /companion, the extension detects the development daemon already listening on port 43721 and does not launch another daemon.

For hot-reloading UI work, keep the daemon running and use:

npm run ui:dev

which proxies /api and /ws to the daemon on 43721.

If you start Gentle Shell from the checkout without running npm run serve, running /companion can still auto-start a local daemon build if one exists under server/target/debug or server/target/release. For predictable UI work, prefer npm run serve in one terminal and gentle-shell -e ./src/index.ts in another.

To regenerate the README screenshots from demo sessions (your running daemon is left alone; the demo daemon uses ports 43731/43732 and a throwaway data folder):

npm run ui:build && cargo build --release --manifest-path server/Cargo.toml
node tools/screenshots.mjs

The generator also refreshes automation list/detail/history/editor/results, automated session, and slash-command suggestions screenshots. Type / in a shared session to search its available extension commands, skills, and prompt templates; use ↑/↓ and Tab/Enter to choose, then send when ready. Built-in terminal-only commands and ordinary tool names are not included. Automated answers-only sessions never expose this picker.

It needs Playwright and cwebp. Set PLAYWRIGHT=/path/to/node_modules/playwright/index.mjs if Playwright isn't installed in this repo, and CHROME=/path/to/chrome to use an existing browser.

To test the same behavior as a published install, stop any development daemon first and install the package normally:

gentle-shell install npm:@rgaricano/gentle-companion

Then start Gentle Shell. Extension startup ensures the released daemon is available; use /remote-control only for sessions you want to share.

Releases

The package carries the required pi-package keyword, which makes the published npm package eligible for discovery in the Pi package gallery (https://pi.dev/packages). The manifest also includes focused discovery keywords such as pi-extension, pi-coding-agent, remote-control, and session-dashboard. Host-provided packages (@earendil-works/pi-coding-agent, typebox) are peer dependencies, as Gentle Shell requires.

GitHub Actions run only for release tags. Pushing ordinary commits or opening pull requests does not trigger any workflow; CI can also be started manually with workflow_dispatch.

A tag matching vX.Y.Z triggers both the CI and release workflows.

Before publishing, the workflow requires X.Y.Z to match both package.json and server/Cargo.toml. It then runs TypeScript and Rust checks, builds native daemon archives for Linux x86_64, macOS arm64, macOS x86_64, and Windows x86_64, generates SHA-256 checksums, and creates a GitHub Release.

Only after the GitHub Release exists, the same tag publishes @rgaricano/gentle-companion to npm with provenance through npm Trusted Publishing (GitHub OIDC). No long-lived NPM_TOKEN is required. The trusted publisher should point to GitHub owner IAI-00-IAI, repository gentle-companion, workflow release.yml. Git installs need no npm credential.

On extension load, Companion downloads gentle-companion-server-<os>-<arch> for its own package version (releases/download/v<version>/) if needed, verifies SHA256SUMS and the binary version, and caches it under ~/.pi/agent/pi-companion/bin/<version>/. Upgrades prepare the replacement before gracefully stopping the older daemon. Git installs ahead of the newest release must provide a matching local build; missing releases never trigger a downgrade or shutdown.

Security boundary

The design follows a few non-negotiable rules:

  • local admin and remote device surfaces use different ports
  • both listeners bind to loopback
  • only the remote listener should ever sit behind a tunnel
  • pairing invitations are single-use and expire after five minutes; wrong short codes are throttled
  • paired-device secrets are stored only as SHA-256 hashes, in a 0600 state file
  • strict Origin checks: the paired-device surface accepts WebSocket upgrades and POST/DELETE only from its own loopback address, the public URL or PI_COMPANION_ALLOWED_ORIGINS, and refuses any foreign Origin; the console accepts only its own loopback origin, so a web page cannot drive Gentle Shell through it
  • remote devices only see sessions with remoteEnabled=true
  • uploads are placed only in daemon-created session sandboxes, within the size limit and optional MIME allowlist
  • file deletion is id-based and boundary checked
  • there is no generic shell endpoint
  • Gentle Shell remains the authority that performs agent actions

Next hardening milestones

  1. Add per-device session permissions in addition to session opt-in.
  2. Bound browser event queues by both item count and bytes, dropping low-priority deltas first.
  3. Add upload count/quota limits per session.
  4. Package signed/notarized daemon binaries and service installation for macOS/Linux/Windows.

License

This fork is distributed under the GNU Affero General Public License, version 3.0, as specified in LICENSE. Code inherited from the original pi-companion project is provided under its MIT license; original files keep their MIT notices, and the preserved original license text is available in LICENSE-MIT.

The optional tunnel feature uses Tailcat, which is licensed under the BSD 3-Clause License; the full text is available in THIRD-PARTY-LICENSES.md.