ompweb

English | 简体中文 | 日本語

Community: Join the OMPWEB Discord

Local web UI for the oh-my-pi (omp) coding agent. ompweb reads your local omp session files and gives you a browser workspace for session browsing, real-time chat, model configuration, skill management, and project file preview.

Dark theme

Requirements

• omp installed and on your PATH (or point OMP_WEB_OMP_BIN at the binary)
• Node.js 22.19.0 or newer (node --version)

Quick Start

Run without installing:

npx @kahme247/ompweb@latest

Or install globally:

npm install -g @kahme247/ompweb
ompweb

Then open http://127.0.0.1:30177. The CLI will try to open the browser automatically after the server is ready. ompweb listens on 127.0.0.1 by default.

Options:

ompweb --port 8080              # custom port
ompweb --hostname 0.0.0.0       # expose on a trusted network
ompweb -p 8080 -H 0.0.0.0       # combine options
ompweb --no-open                # do not open the browser automatically

PORT=8080 ompweb                # environment variable is also supported
OMP_WEB_HOSTNAME=0.0.0.0 ompweb # explicit network exposure
OMP_WEB_PASSWORD='a-long-random-password' ompweb # require Basic Auth (username: omp)
OMP_WEB_NO_OPEN=1 ompweb        # useful when running as a background service

Set OMP_WEB_PASSWORD to protect the interface and every API endpoint with HTTP Basic Auth. The username is always omp; leaving the variable unset disables authentication. Basic Auth does not encrypt traffic, so remote use still requires HTTPS through a trusted reverse proxy or VPN.

Security and troubleshooting

• The server binds to 127.0.0.1 by default. A non-loopback hostname is an explicit opt-in and should only be used behind a trusted network boundary; ompweb is not safe to expose publicly.
• File APIs are allow-listed to the selected workspace, its valid Git worktrees, session-referenced directories, and explicitly selected roots. Paths are canonicalized to reject traversal and symlink escapes.
• omp is resolved from OMP_WEB_OMP_BIN first, then PATH. If live chat cannot start, run omp --version in the same terminal or set OMP_WEB_OMP_BIN to the executable's absolute path.
• Session history remains native OMP JSONL. OMP owns live-session writes; ompweb reads the files directly and only performs explicit title, archive, and delete maintenance when it is not racing a live OMP write.
• Session archive uses OMP's native archive/sessions/<cwd>/<file>.jsonl.gz layout and moves sibling artifacts with the transcript; the original JSONL bytes are preserved inside the gzip.

Features

• Pick work back up: browse previous omp conversations by project without digging through terminal history or session paths.
• Try different directions safely: continue from an earlier message or fork a session into a separate route.
• Keep the sidebar tidy: archive an inactive session without deleting its native transcript, or delete it explicitly when it is no longer needed.
• Work across branches: switch Git worktrees from the sidebar so new sessions and the Explorer follow the checkout you choose.
• Chat beside the project: browse files on the left and preview source, docs, images, audio, and PDFs on the right while the agent works.
• See session state clearly: context usage, cost, compaction state, and system prompt details are visible from the top bar.
• Configure less from the terminal: manage models, login/API keys, model tests, native OMP controls (advisor, approval, Bash policy, thinking, compaction, memory, auto-learn, retry/fallback), skills, plugins, and project MCP servers from the web UI.
• MCP management in Settings: a dedicated MCP tab lists installed project servers with status (enabled / disabled / invalid), supports add/edit/rename/validate/remove, and surfaces configuration failures as corner toasts.
• Keep OMP current: check the installed runtime version, update it, and restart active sessions from Settings when needed.
• Stay informed: opt into browser notifications when an agent finishes, and check installed skills for updates.
• Jump anywhere with ⌘K: a command palette (⌘K / Ctrl+K) for switching sessions, starting new ones, and toggling the theme.
• Warm, paper-like design: light and dark themes with serif display type and WCAG AA-verified contrast, built on a token-driven UI kit (Base UI primitives, cmdk, lucide icons).

Configuration

Variable	Meaning
PORT	Server port (default 30177; -p/--port wins)
OMP_WEB_HOSTNAME	Bind hostname (default 127.0.0.1; -H/--hostname wins)
OMP_WEB_PASSWORD	Optional HTTP Basic Auth password (username: omp)
OMP_WEB_NO_OPEN	Set to 1/true to skip auto-opening the browser
OMP_WEB_OMP_BIN	Absolute path to the omp binary when it is not on PATH
PI_CODING_AGENT_DIR	Point at another omp agent directory (default ~/.omp/agent)
HTTP_PROXY / HTTPS_PROXY / NO_PROXY	Standard proxy variables for server-side requests

Architecture

ompweb is a Node-hosted Next.js app that drives your installed omp binary — it does not embed the agent:

• Live sessions: spawns omp --mode rpc-ui (NDJSON over stdio), one child process per active session, so the agent version is always exactly what you have installed. It negotiates RPC v2 when the installed OMP advertises it, uses bounded chunk reassembly for large frames, and falls back to v1 for older versions.
• Session browsing: reads omp's session files (~/.omp/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl) directly; title, archive, and delete are narrow native-file maintenance operations guarded against live OMP writes.
• Models and auth: RPC commands against the omp child process; the Models panel edits models.yml in the omp agent directory.
• Native settings: the General/MCP settings panels read and write the allow-listed subset of ~/.omp/agent/config.yml (or config.yaml fallback), preserving unrelated keys and comments. Changes apply to new and restarted sessions.
• Skills and plugins: scans omp's skill directories (~/.omp/agent/skills, project .omp/skills, and compat dirs) and shells out to omp plugin for plugin management.
• MCP servers: project servers are managed through OMP's native locations (.omp/mcp.json, then compatibility files) at the git top level, validated against the stdio/http/sse schema and written atomically.
• File access: file browsing and preview are scoped to the selected project directory and working directories that appear in sessions.
• Forks vs in-session branches: Fork creates a new .jsonl file. "Edit from here" creates another branch inside the same session file.

Development

npm install
npm run dev

The local dev server runs at http://127.0.0.1:30178.

Common checks:

npm run typecheck      # type check
npm run lint           # ESLint (zero warnings enforced)
npm test               # run test suite
npm run build          # production build

Avoid running next build / npm run build during local development. It writes to .next/ and can interfere with the dev server; leave builds for release work.

Internationalization

ompweb supports English, Simplified Chinese (简体中文), and Japanese (日本語) with translated UI strings across all three languages. The language is auto-detected from navigator.language and can be switched at runtime via the language menu in the top bar. The choice persists across sessions.

• Dictionaries: lib/i18n/locales/{en,zh-CN,ja}.json
• Framework: lib/i18n/index.tsx — a lightweight store built on useSyncExternalStore with {var} interpolation and plural support (.one/.other)
• API error messages are translated via stable error codes (errors.<code>) looked up client-side

Quality

• Accessibility: WCAG AA compliant — Lighthouse a11y score 100/100, keyboard navigation throughout, focus-visible rings, ARIA roles
• Performance: memoized list components, RAF-gated scroll/mouse handlers, debounced search, streaming JSONL reader, ETag-cached session listing
• Resilience: graceful shutdown of spawned omp processes (process-group kill), error boundaries, atomic session file rewrites
• Tests: a focused test suite covering session parsing, terminal input, markdown rendering, message display, native settings, and MCP configuration

Credits

ompweb is a fork of agegr/pi-web (MIT), the web UI for the earendil/pi-mono pi coding agent, adapted for can1357/oh-my-pi.

License

MIT