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.

Screenshots (light / dark)

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 --package=@kahme247/ompweb@latest ompweb-systemd install

The installer creates ~/.omp/agent/web-service.env automatically with mode 600; no manual file creation is required. The explicit --package form makes npx run the systemd executable from the selected package.

To bind the service to all IPv4 interfaces for LAN access, set a password while installing:

OMP_WEB_HOSTNAME=0.0.0.0 OMP_WEB_PASSWORD='change-me' \
  npx --yes --package=@kahme247/ompweb@latest ompweb-systemd install

Manage it with:

npx --yes --package=@kahme247/ompweb@latest ompweb-systemd status    # Show service state
npx --yes --package=@kahme247/ompweb@latest ompweb-systemd restart   # start / stop / restart
npx --yes --package=@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

On a headless server, enable user lingering if the service must keep running after the last login session ends:

loginctl enable-linger "$USER"

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.
• Message Copy: Copy user messages and completed assistant replies as rendered plain text or original Markdown using the buttons below each message. Thinking, tool output, and message controls are excluded. Oversized messages that use the raw-text viewer copy their full source in either format.
• 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.