ompweb

English | 简体中文 | 日本語

Community: Join the OMPWEB Discord

A clean, modern web UI for the oh-my-pi (omp) coding agent. It reads your local omp sessions and gives you a browser workspace to chat with the agent, browse projects, manage settings, and preview files.

!ompweb — live session demo

Requirements

• omp installed and available on your PATH (or specified via OMP_WEB_OMP_BIN)
• Node.js >= 22.19.0

Quick Start

Run directly without installing:

npx @kahme247/ompweb@latest

or

nix run github:kahme247/ompweb

Or install globally:

npm install -g @kahme247/ompweb
ompweb

Open http://127.0.0.1:30177 in your browser.

CLI Options

ompweb --port 8080                         # Custom port
ompweb --hostname 0.0.0.0                  # Listen on network
ompweb --password "your-password"          # Enable password protection
ompweb --no-open                           # Don't auto-open the browser
ompweb --install-tray                      # Install Windows System Tray service & Desktop shortcuts
ompweb --uninstall-tray                    # Uninstall Windows System Tray service & shortcuts
ompweb --tray                              # Start background System Tray manager
ompweb systemd install                     # Install Linux systemd user service
ompweb --help                              # Show help
ompweb --version                           # Show version

Run as a Windows Service (System Tray)

Install ompweb as a Windows background service with a system tray icon and autostart at login:

ompweb --install-tray

Manage it from Settings → System & Updates → Windows Background Service, or via CLI:

ompweb --tray          # Start the tray manager
ompweb --uninstall-tray

Shortcuts are created on the Desktop and Start Menu. The service restarts automatically and shows the current port and status in the tray.

Run as a macOS Service (launchd)

Install ompweb as a launchd user agent that starts at login and restarts on crash:

npx --yes @kahme247/ompweb@latest ompweb-launchd install

Manage it with:

npx --yes @kahme247/ompweb@latest ompweb-launchd status      # Show service state
npx --yes @kahme247/ompweb@latest ompweb-launchd uninstall   # Stop and remove

The service runs npx --yes @kahme247/ompweb@latest; pass a package spec to pin a version, e.g. ompweb-launchd install @kahme247/[email protected]. All environment variables are read at install time and baked into the plist, plus OMP_WEB_PKG (package spec, same as the positional argument). As a service, the browser is not auto-opened by default — install with OMP_WEB_NO_OPEN=0 to restore that.

OMP_WEB_PASSWORD=secret npx --yes @kahme247/ompweb@latest ompweb-launchd install

When binding to a non-loopback host, require authentication (OMP_WEB_PASSWORD or equivalent access control) and HTTPS through a trusted reverse proxy or VPN. Never expose the unauthenticated web UI or send its password/session cookie over plaintext HTTP.

Logs go to ~/Library/Logs/ompweb/ompweb.log and the plist lives at ~/Library/LaunchAgents/com.kahme247.ompweb.plist (mode 600; a configured password is stored there in plain text).

Run as a Linux Service (systemd)

Install ompweb as a systemd user service that starts at login and restarts on crash:

npx --yes @kahme247/ompweb@latest ompweb-systemd install

Manage it with:

npx --yes @kahme247/ompweb@latest ompweb-systemd status    # Show service state
npx --yes @kahme247/ompweb@latest ompweb-systemd restart   # start / stop / restart
npx --yes @kahme247/ompweb@latest ompweb-systemd uninstall # Stop and remove

The service runs the locally installed ompweb binary resolved at install time (override with OMP_WEB_SYSTEMD_BIN). Runtime configuration lives in ~/.omp/agent/web-service.env — the tray (or any editor) can change the port, hostname, and password there and just restart the service; no reinstall needed. Install-time environment variables are baked into that file. As a service, the browser is not auto-opened by default. The unit lives at ~/.config/systemd/user/ompweb.service and logs go to the journal:

journalctl --user -u ompweb -f

Linux System Tray (KDE Plasma and compatible)

On Linux, ompweb-tray registers a StatusNotifierItem tray icon with a context menu: open the web UI, copy its URL, start/stop/restart the systemd service, view logs, expose the web UI to the network, change the port, set the web password, toggle autostart, and quit the tray.

npx --yes @kahme247/ompweb@latest ompweb-tray --install      # Icons + autostart + start tray
npx --yes @kahme247/ompweb@latest ompweb-tray --status       # Tray and service status
npx --yes @kahme247/ompweb@latest ompweb-tray --uninstall    # Remove autostart, stop tray

Expose to Network rebinds the service from 127.0.0.1 to 0.0.0.0 so the web UI is reachable from your LAN or VPN (e.g. Tailscale). Leaving loopback requires a web password — the tray prompts for one via kdialog/zenity when needed. Change Port… and Set Web Password… edit ~/.omp/agent/web-service.env and restart the service. When binding to a non-loopback host, use HTTPS through a trusted reverse proxy or VPN for remote access.

"Start with Plasma" in the tray menu toggles a desktop autostart entry at ~/.config/autostart/ompweb-tray.desktop. Requires a running StatusNotifierItem host (KDE Plasma, and most Wayland/X11 desktops).

Features

• Interactive Chat: Real-time streaming conversation with your local omp agent — tool calls, thinking levels, token counts, cost, context gauge, queue controls, and interrupt & retry.
• Queue Deletion Confirmation: Preview and confirm before removing queued follow-ups or steered messages from the queue panel. This does not cancel delivery already queued inside OMP.
• Session Management: Browse past conversations by project, fork sessions, branch within a session, archive/restore, import session files, and deep-link via URL.
• Draft Recovery: Unsent text stays scoped to its conversation or new-session workspace and is restored after Back/Forward navigation or reload in the same tab when browser storage is available (up to 50 drafts). Images and file attachments remain in memory only.
• Live Plans & Subagents: Collapsible panels pinned above the composer track live todo phases and running subagents (status, tool, retries, tokens/cost, nested tasks) with transcript dialogs and history recovery.
• Tool Preset Picker: Choose the toolset for new sessions in the composer — none / default (read,bash,edit,write) / full (all tools including subagents). Persists to localStorage.
• File Explorer & Previews: Browse workspaces side-by-side with chat; preview code, markdown, Mermaid, images, audio, PDFs, and diffs with allow-listed access.
• Git Worktree Support: Create, switch, and manage Git worktrees directly from the sidebar; sessions and file roots stay grouped by project.
• Usage & Analytics: Dashboard in Settings → Usage for tokens, costs, cache savings, and breakdowns by provider / model / day / project with SQLite persistence.
• Windows System Tray & Service: Background service, tray icon, logon autostart, and Desktop/Start Menu shortcuts (Windows).
• macOS launchd Service: LaunchAgent that starts at login, restarts on crash, and logs under ~/Library/Logs/ompweb.
• Linux systemd Service & Tray: User service that starts at login and restarts on crash, plus a StatusNotifierItem tray icon with service controls (KDE Plasma and compatible desktops).
• Web-based Settings (8 tabs): Interface & Behavior, Safety & Approvals, AI Model Defaults, API Keys & Providers, Usage, Agent & Intelligence (advisor, memory, compaction), Agents, Extensions & Tools (MCP, skills, plugins), System & Updates.
• Slash Commands & Shortcuts: Quick prompts (/plan, /review, /fix, /test, etc.), ⌘K / Ctrl+K palette, and model/reasoning cycling.
• UI Themes & Localization: Warm paper light/dark themes plus an omp.sh-inspired midnight (omp) theme, chat font size & interface scale, with full English, Chinese (简体中文), and Japanese (日本語) translations.

Environment Variables

| Variable | Description | Default | | --- | --- | --- | | PORT | Server port | 30177 | | OMP_WEB_HOSTNAME | Server bind host | 127.0.0.1 | | OMP_WEB_PASSWORD | Optional password for web login | _None (auth disabled)_ | | OMP_WEB_NO_OPEN | Set to 1 to prevent auto-opening browser | 0 | | OMP_WEB_OMP_BIN | Path to omp binary if not on PATH | _auto-detected_ | | PI_CODING_AGENT_DIR | Custom omp agent directory | ~/.omp/agent | | OMP_WEB_STT_ENDPOINT | OpenAI-compatible transcription endpoint URL | _None (disabled)_ | | OMP_WEB_STT_KEY | Optional API key for the STT endpoint | _None_ | | OMP_WEB_STT_MODEL | Optional model name for the STT endpoint | _None_ |

Development

git clone https://github.com/kahme247/ompweb.git
cd ompweb
npm install
npm run dev

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

Checks

npm run typecheck   # Type check (TypeScript)
npm run lint        # ESLint
npm test            # Run test suite

Note: Do not run npm run build during local dev — it populates .next/ and can break npm run dev.

License & Credits

• Forked from agegr/pi-web (MIT) and adapted for can1357/oh-my-pi.
• Released under the MIT License.