oh-my-agent-web 0.6.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oh-my-agent-web contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,385 @@
+# oh-my-agent-web
+
+[中文](README.md) · **English**
+
+One line: **an external control surface for the agent you're already running.** The engine keeps running on your own machine; you use the web page to watch it work, manage its tools and models, cut in whenever it drifts, and jump into files or a shell when you need to.
+
+Single user, loopback only, and the engine's own on-disk files are the source of truth for conversations — no database, no accounts. One `omaw` process is one person's workbench.
+
+![Four subagents running in parallel in one session: projects and sessions on the left, process and tool cards in the middle, file preview on the right](docs/screenshots/01-chat.png)
+
+```
+npm ci && npm run build && npm start   →   http://127.0.0.1:25257
+```
+
+---
+
+## Modules
+
+The top bar *is* the menu; the sidebar holds projects, sessions and files; the right pane is preview and terminal.
+
+| Module | Where | What it does |
+|---|---|---|
+| **Conversation** | center | Streaming text + collapsible thinking blocks + tool cards (arguments / full command / output / duration / ok or failed) + a "N steps" process block + a usage footer (tokens / cache / cost) + chips for changed files |
+| **Steer & queue** | composer | Cut in mid-turn and the next message takes effect immediately; queued messages can be retracted; sent messages fold into the process block |
+| **Engines** | top bar picker | pi / Codex / DeepSeek Harness / opencode each with its native loop (not one prompt in four costumes); every session remembers its engine, model and thinking level |
+| **Subagents** | top bar "subagents" + the strip under the conversation | The main agent gets an `Agent` tool and can run several **real sessions** in parallel; run cards show status / duration / tool count / tokens / cost, expand in place for the result, and can be stopped individually. The panel manages templates: tool allowlist, model, thinking level, max turns, concurrency (1–12) |
+| **Models & providers** | top bar "models" | The 41 providers in pi's official catalog work **with just a key** — no base URLs, no hand-copied model IDs. Custom providers expose the api shape (openai-completions / responses / anthropic-messages / codex / typesafe), base URL and custom headers; tick models, batch-test speed, pull the list from `/models`, save a whitelist. **Keys never leave the server** (only the last four digits come back) |
+| **Skills** | top bar "skills" | Installed list with enable/disable and a reader for `SKILL.md` plus the skill's files; **Skill Hub** search and one-click install (200k+ index), install from a Git repo, or create by hand. Enabling means renaming `SKILL.md` — there is no second state file |
+| **MCP** | top bar "MCP" | Edit both `mcp.json` files (global and project; a project entry with the same name wins), enable/disable, pick an exposure level (codemode / deferred / direct / hidden), **test the connection** (real handshake + tool list), OAuth login, browse a marketplace |
+| **Plugins** | top bar "plugins" | pi packages (npm / git / local dir) with four states (loaded / installed / missing / disabled), per-package disabling, plus loose single-file extensions; state comes from pi's own resolution — only install/uninstall/update touch the disk |
+| **File manager** | sidebar "files" | Directory tree (switchable root), search by name, show hidden files, collapse all, upload and download, reveal in Finder; uncommitted changes are dotted in the tree |
+| **File viewer** | right pane (multi-tab) | Markdown / source with line numbers / images / PDF / audio-video streams; select lines and "add to conversation" to use them as context; full screen and draggable width |
+| **Diff** | "diff" at the top of the viewer | Compared against HEAD: a `+285 −78` summary, line-level red/green highlighting, switch between diff and full file; opening from a "changed files" chip lands straight on the diff |
+| **git** | top of the files pane | Branch chip (click to switch local branches, confirms first on a dirty tree), `M` / `U` / `D` markers after filenames |
+| **Terminal** | files pane `>_`, right-pane tab | A real PTY (`node-pty` + xterm.js) sharing the session's cwd, with an optional initial command; on Linux it tells you exactly which build tools are missing |
+| **Push** | top bar "push" | Web Push subscriptions (VAPID); one notification per finished turn — title is the project, body the session, with ❌ for failures and ⏹ for interrupts. Multiple devices, test push, clear all; needs https or localhost |
+| **Voice** | top bar "voice" | Four event sounds (start / finish / error / waiting for approval) with preview and volume; local TTS (the browser's own voices, no network) that can read the final reply, with speed and voice selection |
+| **Settings** | top bar "settings" | Four pages: **UI** (which chunks appear in the top bar and status bar), **general** (saved phrases, etc.), **appearance** (chat font size ×4, content width ×4, six palettes: bright white, warm paper, mist, Tokyo night, mocha, nord), **language** (Chinese / English, applies instantly) |
+| **Sessions** | sidebar | Grouped by directory into "projects"; pin, rename, archive (undoable), delete (renames to `.deleted-<timestamp>`, the file survives). A session *is* the engine's own file — identical to what the CLI shows |
+| **Attachments** | composer | Drag-and-drop upload, `@` file mentions, pasted images; uploads land in the data dir, never in your project |
+| **Mobile** | — | Responsive: the sidebar becomes a drawer, process blocks collapse to a caret, below 400px it switches to the phone layout |
+
+> Every screenshot below comes from a **real, running instance** (taken on this project's own session) — nothing is mocked up.
+
+---
+
+## Screens
+
+| | |
+|---|---|
+| ![Answer with a markdown table, changed files and usage](docs/screenshots/02-answer.png) | ![Diff view of a file](docs/screenshots/03-files-diff.png) |
+| **Answer**: markdown, tables, code highlighting, token and cost footer | **Diff**: against HEAD, line-level red/green |
+| ![Embedded terminal](docs/screenshots/04-terminal.png) | ![Models and providers](docs/screenshots/05-models.png) |
+| **Terminal**: a real PTY in the session's cwd | **Models**: the 41 built-ins need only a key; ticked models apply |
+| ![Skills panel](docs/screenshots/06-skills.png) | ![Skill Hub](docs/screenshots/07-skills-hub.png) |
+| **Skills**: installed list, toggles, and `SKILL.md` | **Skill Hub**: search by category, install in one click |
+| ![MCP](docs/screenshots/08-mcp.png) | ![Subagents](docs/screenshots/09-subagents.png) |
+| **MCP**: global and project config, exposure, connection test | **Subagents**: who is running, results, templates and tool allowlists |
+| ![Settings](docs/screenshots/10-settings.png) | ![Plugins](docs/screenshots/11-plugins.png) |
+| **Settings → appearance**: font size, width, six palettes | **Plugins**: load state of pi packages, with toggles |
+
+Two more: [voice (event sounds + local TTS)](docs/screenshots/12-voice.png), [push (subscriptions and devices)](docs/screenshots/13-push.png).
+
+---
+
+## Quick start
+
+Requires **Node.js ≥ 22.19** (a hard requirement of `@earendil-works/pi-*` 1.x) and **npm ≥ 9**. macOS / Linux / Windows all work.
+
+```bash
+npm ci               # recommended: exact versions from the lockfile (no re-resolution)
+npm run build
+npm start            # foreground; Ctrl-C to quit
+```
+
+Open <http://127.0.0.1:25257>.
+
+### One-line install (never touches global npm)
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/main/scripts/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/main/scripts/install.ps1 | iex"
+```
+
+The script does four things: **finds a new enough Node** (downloading the official build into `~/.omaw/node` with a sha256 check if needed), **runs `npm install -g --prefix ~/.omaw`** (no system-wide directory, no sudo), **links `omaw` into `~/.local/bin`** (patching PATH if necessary), and **smoke-tests once** (version string plus whether `node-pty` can be required — i.e. whether the terminal will open).
+
+| What you want to change | How (`sh` version; the PowerShell version uses env vars) |
+|---|---|
+| Version | `OMAW_VERSION=0.7.0` (or `--version 0.7.0`) |
+| Install location | `OMAW_HOME=/opt/omaw` (or `--home /opt/omaw`) |
+| Registry mirror | `OMAW_REGISTRY=https://registry.npmmirror.com` (or `--registry …`) |
+| Leave PATH alone | `OMAW_NO_PATH=1` (or `--no-modify-path`) |
+| Install build tools | `OMAW_BUILD_TOOLS=1` (or `--with-build-tools`) |
+| Uninstall | `… \| sh -s -- --uninstall` (removes the install dir and symlink only, never your data dir) |
+
+On Linux the script also checks for `make` / `g++` / `python3`: `node-pty` ships prebuilds for macOS / Windows only, so Linux compiles the PTY in place. If the tools are missing it tells you what to install, or you can pass `--with-build-tools` and let it handle that.
+
+> You can also just type `omaw` in your home directory after installing, but the home directory is an unsafe workspace (the file tree, search and the agent's cwd would all be your entire home). In that case it falls back to `<dataDir>/workspace` and prints a note. To point it at a real project use `AGENT_WEB_CWD=/path/to/project`.
+
+### Install as a global command
+
+`oh-my-agent-web` / `omaw` / `agent-web` are three bin names for the same entry point:
+
+```bash
+npm i -g .
+omaw -d              # start in background (logs to <dataDir>/daemon.log)
+omaw status          # pid / port / uptime / engine / session count
+omaw restart -d      # restart after code changes
+omaw stop
+omaw version         # current version; omaw upgrade upgrades to the latest release
+```
+
+### CLI flags
+
+| Flag | Env var | Default | Notes |
+| --- | --- | --- | --- |
+| `-p, --port` | `AGENT_WEB_PORT` | `25257` | Listen port |
+| `-H, --host` | `AGENT_WEB_HOST` | `127.0.0.1` | Bind address; only change it for remote access |
+| `-P, --password` | `AGENT_WEB_PASSWORD` | none | Access password; unset = local machine only |
+| `--allow-host` | `AGENT_WEB_ALLOWED_HOSTS` | loopback only | Extra allowed domains / LAN IPs (repeatable or comma-separated) |
+| `--data-dir` | `AGENT_WEB_DATA_DIR` | `~/.oh-my-agent-web` | Settings, password, uploads, logs, lock file |
+| — | `AGENT_WEB_CWD` | `process.cwd()` | Default workspace (used before any session exists) |
+| — | `AGENT_WEB_ENGINE` | `pi` | Default engine |
+| — | `AGENT_WEB_APPROVAL_MODE` | `allow` | Default approval mode for new sessions; set `ask` to confirm every time |
+| — | `AGENT_WEB_TURN_TIMEOUT_MS` | 20 min | Per-turn watchdog timeout |
+| — | `AGENT_WEB_LOG` | `info` | `debug` / `info` / `warn` / `error` |
+
+> To use it from your phone: `omaw -d -H 0.0.0.0 -P your-password --allow-host your.domain`. If you put a reverse proxy or tunnel in front, make sure it forwards `X-Forwarded-For` (origin checks look at it).
+
+---
+
+## UI tour
+
+```
+┌─ top bar: brand · new chat · engine picker · subagent badge · panels · right-pane toggle ─┐
+├────────────┬──────────────────────────────┬──────────────────────┤
+│ sidebar    │ conversation                  │ right pane           │
+│ · projects │ · message stream (thinking    │ · file preview        │
+│ · sessions │   blocks + tool cards)        │   (multi-tab)         │
+│ · archived │ · steer / queued messages     │ · terminal            │
+│ · files    │ · subagent run strip          │ · status bar          │
+│            │ · composer (attachments, /)   │                      │
+└────────────┴──────────────────────────────┴──────────────────────┘
+```
+
+The sidebar and right pane can both be dragged wider or collapsed; widths persist in `localStorage`. The composer takes `/` slash commands, `@` file mentions, drag-and-drop attachments and pasted images; the chips above it are prompt templates, the thinking toggle and suggested actions.
+
+On narrow screens (mobile UA or ≤400px) the layout switches to overlay drawers and the sidebar collapses shortly after you pick a session. Which chunks appear in the top bar and status bar — and whether process blocks start expanded — are all switchable in settings.
+
+---
+
+## Engines
+
+| Engine | Notes |
+| --- | --- |
+| **pi** (default) | The full plugin / skill ecosystem, lazy tool loading, approval gate, goal mode and subagents; providers and models are managed by this workbench |
+| **Codex** | The official Codex agent (app-server JSON-RPC) with its own loop and sandbox; sessions are shared with Codex Desktop / CLI; approvals are command/file level |
+| **DeepSeek Harness** | The official DeepSeek agent (ACP); model and thinking level are switchable; permissions confirmed one by one |
+| **opencode** | The official opencode agent (ACP) with its own tools / MCP / plugin ecosystem; sessions are shared with the opencode CLI / TUI. **Approvals follow opencode's own `permission` config** (a global allow means you will never be asked) |
+| **fake** | A scripted, zero-token engine used only to exercise the protocol / tools / approvals (`AGENT_WEB_ENGINE=fake`, not shown in the picker by default) |
+
+Capability matrix (`server/engine/registry.ts`):
+
+| Capability | pi | codex | dsh | opencode |
+| --- | :-: | :-: | :-: | :-: |
+| Approvals | ✅ | ✅ | ✅ | per config |
+| Model / thinking level | ✅ | ✅ | ✅ | ✅ |
+| Resume sessions | ✅ | ✅ | ✅ | ✅ |
+| Steering | ✅ | — | — | — |
+| Subagent panel | ✅ | — | — | — |
+| Workbench-managed providers | ✅ | — | — | — |
+
+A missing engine does not block startup: you only get "not found" when you switch to it.
+
+Per-engine escape hatches (all have defaults, usually leave them alone):
+
+| Variable | Purpose |
+| --- | --- |
+| `AGENT_WEB_OPENCODE_BIN` / `_ARGS` / `_MODEL` | opencode binary, extra args (e.g. `--pure` to skip external plugins), preferred model for new sessions (`provider/model`) |
+| `AGENT_WEB_DSH_BIN` / `_HOME` / `_MODEL` / `_PATCH` | DSH binary, data dir, model, patch toggle |
+| `AGENT_WEB_CODEX_BIN` / `_HOME` | Codex binary and data dir |
+
+---
+
+## Sessions and on-disk state
+
+No database: **the engine's own files are always the source of truth** for a conversation. The web UI only reads them, renames them, and deletes them when asked.
+
+| What | Where |
+| --- | --- |
+| pi sessions | `~/.pi/agent/sessions/<encoded cwd>/<ISO>_<uuid>.jsonl` (first line `{type:"session",id,timestamp,cwd}`) |
+| Codex sessions | Codex's own thread store (via `thread/list \| resume \| delete`) |
+| opencode / DSH sessions | Their own data dirs (opencode lists by cwd; DSH reads the workspace projection under `~/.dsh`) |
+| Session title | pi takes the first user message (reads only the first 60 lines); renaming appends `session_info.name` to the end of the jsonl |
+| Workbench state | `<dataDir>/settings.json`, `approval-rules.json`, `server.lock`, `logs/`, `uploads/`, `push-subscriptions.json`, `vapid-keys.json` |
+
+"Delete session" **renames to `.deleted-<timestamp>`** (native delete APIs win when the engine has one). The file stays on disk and can be recovered.
+
+---
+
+## Models and providers
+
+The models panel groups providers into two columns: **official built-ins** (the ones pi's catalog has models for) and **custom providers**.
+
+- Built-ins need only **an API key** — endpoint and model table come from pi's catalog.
+- Custom providers let you add models, edit base URLs, **import** from another client (actually `GET {baseUrl}/models` and tick the ones you want) and **test each one**.
+- **Keys never leave the server**: the API returns only `hasKey` and the last four digits; writes are serialized inside the process so concurrent edits can't corrupt files.
+
+The config truth is spread over three files plus the engine catalog: `~/.pi/agent/models.json` (pi's own writable provider catalog), `models-store.json` (legacy location), `auth.json` (`api_key` or oauth subscription credentials), with the allowlist in `settings.json.enabledModels`.
+
+---
+
+## Approvals and security model
+
+- Binds `127.0.0.1` by default and validates `Origin` / `Host` (including the `AGENT_WEB_ALLOWED_HOSTS` allowlist, the vite port and LAN addresses).
+- Identity: loopback peer **and** loopback Host → allowed. With no password set, remote requests always get 403. With a password, either the cookie (`agent-web-auth`, 7 days, HttpOnly) or HTTP Basic will do; failed logins are throttled at 20 attempts / 10 minutes.
+- Tools and commands go through approvals: **read-only tools** (read / grep / find / ls) and read-only commands pass automatically, everything else is asked per `scopeKey` (tool + executable name or target directory). Picking "always allow" writes the rule into `approval-rules.json` (atomic write; a corrupt file is treated as empty).
+- When a turn ends, every pending approval for that session is cleared so nothing hangs waiting for a human.
+- Uploaded temp files and session caches live in the data directory, never in your project.
+
+> Exposing it remotely is explicit: `-H`, `-P` and `--allow-host` must all be present, or it won't work.
+
+---
+
+## Subagents (parallel, manageable)
+
+The pi engine ships its own subagent implementation (**no pi-subagents plugin required**):
+
+- **How**: the main agent gets an `Agent` tool (`subagent_type` / `prompt` / `description` / `run_in_background`) and can run several at once. Every delegation is **a real pi session** with its own context, session file and tool allowlist.
+- **Where to watch**: run cards appear under the conversation (the strip above the composer) with status, duration, tool count, tokens and cost. Expand one to see the raw result and its session file path, and stop any of them at any time. Switching sessions swaps the strip to that session's runs. A top-bar badge gives the at-a-glance count.
+- **Management**: the panel manages **templates** (built-in explore / general-purpose / plan, each disableable; create / edit / delete your own). Templates live at `~/.pi/agent/agents/*.md` with frontmatter `name / display_name / description / tools / model / thinking / max_turns`; the body is the system prompt — the same format pi uses, so they're readable, editable and git-friendly.
+- **Concurrency**: a cap of 1–12 (default 4) in the panel; extra delegations queue. Turn the master switch off and the model no longer sees the `Agent` tool.
+- **Isolation**: subagents load no skills / plugins / themes / context files by default (fast and predictable). They inherit the parent's model when they don't pin their own. Models registered by extensions fail inside subagents with "specify a model in the template".
+
+Subagent session files are archived next to the parent session (`<parent session dir>/<parent name>/subagents/`) and never appear in the sidebar.
+
+---
+
+## MCP · plugins · skills
+
+**MCP**: reads and writes `~/.pi/agent/mcp.json` (global) plus `<workspace>/.pi/mcp.json` (project), where a project entry with the same name overrides the global one. Writes preserve indentation and CRLF.
+Exposure has four levels `codemode | deferred | direct | hidden` and tools are namespaced `mcp__<name>`.
+**The config is the truth** — pi connects at session start, so panel changes apply to **new sessions**. Testing a connection does a real handshake with `@earendil-works/pi-mcp` (`tools/list`) and disconnects immediately; OAuth goes through `pi mcp login`. There's also a marketplace (registry / smithery / github) and a "paste a command / URL / JSON and let it parse" flow.
+
+**Plugins**: these are pi packages — `settings.json`'s `packages` (npm / git / local) plus loose `~/.pi/agent/extensions/` and `<ws>/.pi/extensions/`. State is decided by the pi SDK's `resolve()` (querying **never** triggers `npm install`), with four states: `loaded / installed / missing / disabled`. Disabling writes `autoload:false` and deletes nothing.
+
+**Skills**: read from `~/.agents/skills/<dir>/SKILL.md`; the list parses frontmatter only (no yaml dependency) and caps the file listing at 200 entries.
+**Toggling = renaming `SKILL.md` to `.SKILL.md.disabled`** — there is no second state file. Skill Hub supports category search plus zip installs, and git clone can target `skills/<name>`.
+
+---
+
+## Architecture: SSE + RPC, no WebSocket
+
+Early versions used WS; today there are **only two HTTP channels** (ADR-0032):
+
+```
+browser ──GET  /api/events (SSE)──▶ server   snapshot · message_delta · notice
+        ──POST /api/rpc   (JSON)──▶          ClientRequest → { reply } consumed in place
+```
+
+- **Downstream**: one full snapshot first, then deltas only. Message text arrives as `message_delta` chunks; structural changes (tool cards, errors, state) push a new snapshot, coalesced in a 60 ms window — snapshots are droppable, events are not. SSE sends a heartbeat every 25 s and supports gzip `Z_SYNC_FLUSH`.
+- **Upstream**: `send_message` (text / attachments / mode), `interrupt`, `approve`, `new_chat`, `switch_conversation`, `set_engine` / `set_model` / `set_thinking_level` / `set_approval_mode`, `cancel_queued`, `rename_session`, and a handful for providers and subagents.
+- **The protocol lives in one place**, `server/protocol.ts`, and the frontend reuses its types; unit tests keep both ends aligned.
+- **The snapshot is the single source of truth**: the frontend's `store.ts` uses `useSyncExternalStore` and replaces state wholesale when a snapshot arrives. Locally it keeps only optimistic state like `preview` / `draft` / `pendingActive`.
+
+**Process model**: `cli.ts` parses flags → `session/lock.ts` grabs `<dataDir>/server.lock` (`{pid,port,startedAt}`; a live pid means refuse to start, a dead pid means take over the stale lock) → `runtime.init()` → `listen`. `SIGINT/SIGTERM` and `/api/shutdown` share one graceful shutdown path (flush, disconnect engines, release the lock).
+
+---
+
+## Development
+
+```bash
+npm run dev          # starts both processes with one command
+```
+
+- Externally there is still a single port **25257** (Vite listens and proxies); the backend hides on internal **25258**, so dev and prod use the same URL.
+- Frontend HMR via Vite, backend auto-restart via `tsx --watch`.
+- Phone debugging: `npm run dev -- --host 0.0.0.0`.
+
+| Command | Purpose |
+| --- | --- |
+| `npm test` | `node --test` over `tests/unit/*.test.ts` (22 files, no extra dependencies) |
+| `npm run typecheck` | Two `tsc --noEmit` runs: server + web |
+| `npm run lint` | oxlint over `server` / `web/src` / `scripts` |
+| `npm run format` | Prettier across the repo (`format:check` only checks; `*.md` is deliberately skipped) |
+| `npm run build` | Server `tsc` + frontend `vite build` into `web/dist` |
+| `npm run icons` | Regenerate PWA icons with playwright-core |
+
+CI (`.github/workflows/ci.yml`): `npm ci` → typecheck → lint → test → build, on ubuntu + Node 22.
+
+### Directory layout
+
+```
+oh-my-agent-web/
+├─ server/                 Backend (Express 5, TypeScript ESM)
+│  ├─ cli.ts               Command entry: start / stop / restart / status / version / upgrade
+│  ├─ index.ts             Process assembly: middleware, routes, static assets, graceful exit
+│  ├─ protocol.ts          Single source for the protocol (frontend reuses the types)
+│  ├─ engine/              Engine adapters: pi (native SDK) / codex / dsh / opencode (ACP) / fake
+│  │                       plus the capability matrix (registry), catalog, wiring, pi-plugins
+│  ├─ session/             Runtime: runtime, turn-*, approval bridge, rename/delete, lock, settings
+│  ├─ sessions/            HTTP routes for deleting sessions (scanning lives in session/pi-sessions.ts)
+│  ├─ snapshot/            Server state snapshots: state, buildSnapshot, fan-out, 60 ms coalescing
+│  ├─ http/                auth, live-routes (SSE + RPC), aux-routes, compression, file headers
+│  ├─ files/               File tree, preview, search, media streaming, git branches
+│  ├─ terminal/            PTY sessions and their SSE stream
+│  ├─ approval/            Approval scopes and rules
+│  ├─ providers/           Providers / model catalogs / probes / imports / subscription OAuth
+│  ├─ mcp/                 mcp.json read-write, connectivity probe, OAuth, marketplace
+│  ├─ skills/              Skill discovery, toggling, Hub installs
+│  ├─ subagents/           Subagent template storage (`~/.pi/agent/agents/*.md`)
+│  ├─ plugins/             HTTP routes for plugin packages
+│  ├─ push/                Web Push (VAPID)
+│  ├─ markers/             Parsing and stream-filtering `[[action:suggest:…]]` markers
+│  └─ util/                env, paths, spawn-cli (cross-platform), origin, etc.
+├─ web/                    Frontend (React 19 + Vite + TypeScript)
+│  ├─ src/components/      ~70 components: sidebar, message stream, composer, file tree, terminal, panels
+│  ├─ src/styles/          ~45 sectioned CSS files + six theme palettes (no CSS framework)
+│  ├─ src/ws.ts            SSE + RPC client (the name is historical)
+│  └─ src/store.ts         Snapshot store (useSyncExternalStore)
+├─ scripts/                Dev dual-process, installers, prebuild pruning, icon generation
+├─ tests/unit/             node:test unit tests
+├─ docs/adr/README.md      ADR index
+└─ docs/screenshots/       Real screenshots used by the READMEs (PNG 256 colors, ~1.4 MB)
+```
+
+### Code conventions
+
+- Prettier: **tab indentation**, `printWidth 120`. oxlint runs its default rule set.
+- 400 lines per file is a guardrail; exceeding it means splitting (`cli-info.ts` and `snapshot/*` exist for that reason).
+- **ADR prose lives in the file-header comment of the code it constrains**, not in standalone `docs/` files — anyone editing the code will read it. `docs/adr/README.md` is only an index from number to file. Update that table when you change the code.
+
+---
+
+## Install size: pick the command that fits
+
+Most of the dependency tree is frontend build-time weight (`mermaid` alone is 121 MB, plus React) and build tools that only matter on your machine. At runtime the server needs just
+`express` / `web-push` / `node-pty` / `@earendil-works/pi-*` — the browser half already ships as `web/dist`.
+That's why `react` / `mermaid` / `xterm` / `highlight.js` all live in `devDependencies`:
+
+| Scenario | Command | Packages | Disk |
+|---|---|---|---|
+| Developing / building yourself | `npm ci` | 456 | 547 MB |
+| Already built, just run it | `npm ci --omit=dev` | 192 | **158 MB** (~3 s) |
+| Build then slim down | `npm ci && npm run build && npm prune --omit=dev` | 192 | **158 MB** |
+| Ship to another machine | `npm pack` → `npm i -g ./oh-my-agent-web-*.tgz` | 193 | 223 MB (3.1 MB tarball, README screenshots included) |
+
+Two automatic slimming steps run in `postinstall` (`scripts/prune-prebuilds.mjs`):
+
+- **Keep only the current platform's `node-pty` prebuilds**: the package ships binaries for four platforms, and the two Windows ones alone are 58 MB. Pruning on macOS / Linux takes 62 MB → 5 MB; `npm ci` restores them as-is.
+- Fix the executable bit on `spawn-helper`.
+
+> Of the remaining 158 MB, almost everything is pi's model layer: the official SDKs for each provider (`openai` 17.6 MB, `@google/genai` 10.8 MB, `@anthropic-ai/sdk` 9.1 MB, `@aws-sdk/*` + `@smithy/*` 5.2 MB) —
+> all hard dependencies of `@earendil-works/pi-ai`, unavoidable without trimming vendors.
+
+---
+
+## Troubleshooting
+
+> **Why `npm ci` and not `npm install`**: this project's direct dependencies are all very new (most within a month of release).
+> `npm install` re-resolves the version ranges from `package.json` against the registry, so if your mirror (corporate Nexus, npmmirror, etc.) hasn't synced those versions yet you get `npm error notarget No matching version found for …`.
+> `npm ci` uses the exact versions from the lockfile and never touches that path.
+
+Check these in order:
+
+1. `npm error notarget No matching version found` → the mirror is behind. Check `npm config get registry`, then retry against the official one: `npm ci --registry=https://registry.npmjs.org/`.
+2. `EBADENGINE` / pi complains about the Node version right at startup → you need Node ≥ 22.19 (`node -v`).
+3. `node-pty` fails to build (mostly on Linux) → prebuilds ship for macOS / Windows only, so Linux compiles it in place and needs `python3`, `make`, `g++`.
+4. Won't start but `omaw status` mentions a stale lock → a previous process didn't exit cleanly; the next `start` takes over automatically. If it's truly stuck, delete `<dataDir>/server.lock`.
+5. Port already in use → `omaw -p 25258`, or run `omaw stop` first.
+
+Windows pitfalls we've already hit (shell parsing, killTree, path checks, chmod, CRLF) are catalogued with P0/P1/P2 severities in `WINDOWS-COMPAT.md`.
+
+---
+
+## License
+
+MIT