ompgui 0.4.0

package/README.ko.md

@@ -0,0 +1,183 @@
+# ompweb
+
+[English](./README.md) | [한국어](./README.ko.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md)
+
+[oh-my-pi (omp) 코딩 에이전트](https://github.com/can1357/oh-my-pi)를 위한 로컬 웹 UI입니다. ompweb은 로컬 omp 세션 파일을 읽어 브라우저에서 세션 탐색, 실시간 채팅, 모델 설정, 스킬 관리, 프로젝트 파일 미리보기를 제공하는 워크스페이스를 엽니다.
+
+![ompweb — 라이트 테마](docs/screenshot-light.png)
+
+<details>
+<summary>다크 테마</summary>
+
+![ompweb — 다크 테마](docs/screenshot-dark.png)
+
+</details>
+
+## 요구 사항
+
+- [omp](https://github.com/can1357/oh-my-pi)가 설치되어 `PATH`에 있어야 합니다(또는 `OMP_WEB_OMP_BIN`으로 바이너리를 지정).
+- Node.js 22.19.0 이상(`node --version`)
+
+## 빠른 시작
+
+**설치 없이 실행:**
+
+```bash
+npx ompgui@latest
+```
+
+**또는 전역 설치:**
+
+```bash
+npm install -g ompgui
+ompweb
+```
+
+그다음 [http://127.0.0.1:30177](http://127.0.0.1:30177)을 여세요. 서버가 준비되면 CLI가 브라우저를 자동으로 열려고 시도합니다. ompweb은 기본적으로 `127.0.0.1`에서 수신합니다.
+
+**옵션:**
+
+```bash
+ompweb --port 8080              # 포트 지정
+ompweb --hostname 0.0.0.0       # 신뢰할 수 있는 네트워크에 노출
+ompweb -p 8080 -H 0.0.0.0       # 옵션 조합
+ompweb --no-open                # 브라우저 자동 열기 안 함
+ompweb --password "a-long-random-password" # POSIX 인라인 환경 변수 없이 비밀번호만으로 로그인
+
+PORT=8080 ompweb                # 환경 변수도 지원
+OMP_WEB_HOSTNAME=0.0.0.0 ompweb # 네트워크에 명시적으로 노출
+OMP_WEB_PASSWORD='a-long-random-password' ompweb # 환경 변수 방식(POSIX: 인라인 또는 export)
+OMP_WEB_NO_OPEN=1 ompweb        # 백그라운드 서비스로 실행할 때 유용
+
+# Windows (PowerShell / CMD)
+# $env:OMP_WEB_PASSWORD="a-long-random-password"; ompweb
+# 또는
+# ompweb --password "a-long-random-password"
+```
+
+`OMP_WEB_PASSWORD`를 설정하거나 `--password`를 전달하면 테마가 적용된 비밀번호 전용 로그인 화면으로 인터페이스와 모든 API 엔드포인트를 보호합니다. 로그인에 성공하면 30일 동안 유효한 HTTP 전용 서명 세션 쿠키가 생성됩니다. 설정된 비밀번호를 변경하면 기존 세션이 무효화됩니다. 변수를 설정하지 않으면 인증이 비활성화됩니다. 원격 사용 시 비밀번호와 세션 쿠키가 가로채이지 않도록 신뢰할 수 있는 리버스 프록시나 VPN을 통해 HTTPS를 사용해야 합니다. Windows 환경 변수 문법은 `$env:OMP_WEB_PASSWORD="..."`이며, `ompweb --password "..."`는 별도 문법 없이 모든 셸에서 작동합니다.
+
+## 원격 및 모바일 접속 (Tailscale 권장)
+
+외부나 모바일 기기(iPhone, iPad, Android)에서 로컬 PC의 `ompweb`에 접속할 때는 **[Tailscale](https://tailscale.com/) 가상 사설망(VPN)을 사용하는 것을 강력히 권장**합니다. 포트 포워딩이나 공인 IP 노출 없이 종단간 암호화(P2P)를 통해 가장 안전하게 원격 접속할 수 있습니다.
+
+### 1. 비밀번호 설정 (보안 필수)
+
+외부 네트워크에 바인딩할 때는 인증 보호를 위해 반드시 비밀번호를 설정해야 합니다:
+
+```bash
+# CLI 옵션으로 비밀번호 설정 및 전체 네트워크 바인딩
+ompweb -H 0.0.0.0 --password "your-strong-password"
+
+# 또는 환경 변수로 설정
+OMP_WEB_HOSTNAME=0.0.0.0 OMP_WEB_PASSWORD="your-strong-password" ompweb
+```
+
+### 2. Tailscale 연결 단계
+
+1. **Tailscale 설치**: 호스트 PC와 모바일 기기에 [Tailscale](https://tailscale.com/download)을 설치하고 동일한 계정으로 로그인합니다.
+2. **호스트 PC에서 ompweb 실행**:
+   ```bash
+   ompweb --hostname 0.0.0.0 --password "your-strong-password"
+   ```
+3. **모바일 브라우저에서 접속**:
+   - 호스트 PC의 Tailscale IP(예: `100.x.y.z`) 또는 MagicDNS 머신 이름으로 접속합니다:
+     ```text
+     http://100.x.y.z:30177
+     # 또는 MagicDNS 활성화 시
+     http://my-macbook:30177
+     ```
+4. **로그인**: 설정한 비밀번호를 입력하면 모바일에서도 안전하게 실시간 코딩 에이전트와 대화하고 작업할 수 있습니다.
+
+### 보안 및 문제 해결
+
+- 서버는 기본적으로 `127.0.0.1`에 바인딩됩니다. 루프백이 아닌 호스트 이름은 명시적으로 선택해야 하며 신뢰할 수 있는 네트워크 경계 뒤에서만 사용하세요. ompweb을 공개적으로 노출하는 것은 안전하지 않습니다.
+- 파일 API는 선택한 워크스페이스, 유효한 Git worktree, 세션에서 참조된 디렉터리, 명시적으로 선택한 루트만 허용합니다. 경로를 정규화하여 경로 탈출과 심볼릭 링크 탈출을 차단합니다.
+- `omp`는 먼저 `OMP_WEB_OMP_BIN`, 다음으로 `PATH`에서 확인합니다. 실시간 채팅을 시작할 수 없으면 같은 터미널에서 `omp --version`을 실행하거나 실행 파일의 절대 경로를 `OMP_WEB_OMP_BIN`에 설정하세요.
+- 세션 기록은 기본 OMP JSONL 형식으로 유지됩니다. 실시간 세션 쓰기는 OMP가 담당하며, ompweb은 직접 파일을 읽고 실시간 OMP 쓰기와 충돌하지 않을 때만 명시적인 제목·보관·삭제 작업을 수행합니다.
+- 세션 보관은 OMP의 기본 `archive/sessions/<cwd>/<file>.jsonl.gz` 레이아웃을 사용하며, 트랜스크립트와 함께 관련 아티팩트를 이동합니다. 원본 JSONL 바이트는 gzip 안에 보존됩니다.
+
+## 기능
+
+- **이전 작업 이어가기**: 터미널 기록이나 세션 경로를 뒤지지 않고 프로젝트별로 이전 omp 대화를 탐색합니다.
+- **안전하게 다른 방향 시도하기**: 이전 메시지에서 계속하거나 세션을 별도 경로로 포크합니다.
+- **깔끔한 사이드바 유지**: 기본 트랜스크립트를 삭제하지 않고 비활성 세션을 보관하거나, 더 이상 필요하지 않을 때 명시적으로 삭제합니다.
+- **브랜치 간 작업**: 사이드바에서 Git worktree를 전환하면 새 세션과 Explorer가 선택한 체크아웃을 따릅니다.
+- **프로젝트 옆에서 채팅**: 왼쪽에서 파일을 탐색하고 오른쪽에서 소스, 문서, 이미지, 오디오, PDF를 미리 보면서 에이전트의 작업을 확인합니다.
+- **정확한 Markdown 미리보기**: YAML frontmatter를 요약 카드(제목 및 키/값 행)로 렌더링하고, 수식 펜스를 목록 안에서도 정렬하며, `5~7U` 같은 CJK 범위를 올바르게 표시합니다(GFM에서는 취소선에 이제 `~~`가 필요합니다).
+- **Windows에서 자연스럽게 프로젝트 선택**: 파일 시스템 루트의 드라이브 선택기와 대소문자 무시·심볼릭 링크 인식 프로젝트 식별자로 드라이브와 worktree 사이에서도 사이드바를 안정적으로 유지합니다.
+- **세션 상태 명확히 확인**: 상단 바에서 컨텍스트 사용량, 비용, 압축 상태, 시스템 프롬프트 세부 정보를 확인합니다.
+- **터미널 설정 줄이기**: 웹 UI에서 모델, 로그인/API 키, 모델 테스트, OMP 기본 제어(어드바이저, 승인, Bash 정책, 추론, 압축, 메모리, 자동 학습, 재시도/폴백), 스킬, 플러그인, 프로젝트 MCP 서버를 관리합니다.
+- **Settings에서 MCP 관리**: 전용 MCP 탭에서 설치된 프로젝트 서버의 상태(활성화/비활성화/잘못됨)를 확인하고 추가·편집·이름 변경·검증·삭제를 수행하며 설정 오류를 코너 토스트로 표시합니다.
+- **OMP 최신 상태 유지**: Settings에서 설치된 런타임 버전을 확인하고 업데이트하거나 필요할 때 활성 세션을 재시작합니다.
+- **완료 알림 받기**: 에이전트가 작업을 마치면 브라우저 알림을 받도록 선택하고 설치된 스킬의 업데이트를 확인합니다.
+- **⌘K로 어디서든 이동**: 명령 팔레트(⌘K / Ctrl+K)로 세션 전환, 새 세션 시작, 테마 변경을 수행합니다.
+- **따뜻한 종이 느낌의 디자인**: 세리프 디스플레이 글꼴과 WCAG AA 검증 대비를 사용하는 라이트/다크 테마를 토큰 기반 UI 키트(Base UI primitives, cmdk, lucide 아이콘)로 구현했습니다.
+
+## 설정
+
+| 변수 | 의미 |
+| --- | --- |
+| `PORT` | 서버 포트(기본 `30177`; `-p/--port`가 우선) |
+| `OMP_WEB_HOSTNAME` | 바인딩할 호스트 이름(기본 `127.0.0.1`; `-H/--hostname`이 우선) |
+| `OMP_WEB_PASSWORD` / `--password` | 로그인 화면의 비밀번호. `--password`는 PowerShell/CMD에서도 `$env:` 문법 없이 사용 가능 |
+| `OMP_WEB_NO_OPEN` | `1` 또는 `true`로 설정하면 브라우저 자동 열기 건너뜀 |
+| `OMP_WEB_OMP_BIN` | `PATH`에 `omp`가 없을 때 사용할 절대 경로 |
+| `PI_CODING_AGENT_DIR` | 다른 omp 에이전트 디렉터리 지정(기본 `~/.omp/agent`) |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 서버 측 요청에 사용하는 표준 프록시 변수 |
+
+## 아키텍처
+
+ompweb은 Node가 호스팅하는 Next.js 앱으로, 설치된 `omp` 바이너리를 구동합니다. 에이전트를 내장하지 않습니다.
+
+- **실시간 세션**: `omp --mode rpc-ui`(stdio 기반 NDJSON)를 실행하며 활성 세션마다 자식 프로세스를 하나씩 사용합니다. 설치된 OMP가 RPC v2를 알리면 v2를 협상하고, 큰 프레임은 제한된 청크 재조립을 사용하며, 구버전은 v1로 폴백합니다. 실행 전 호스트 환경(`PORT`, `NEXT_*`, `NODE_ENV`)을 제거하고 POSIX(프로세스 그룹)와 Windows(`taskkill /t`) 모두 정상 종료를 지원합니다.
+- **세션 탐색**: omp 세션 파일(`~/.omp/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`)을 직접 읽습니다. 제목·보관·삭제는 실시간 OMP 쓰기를 보호하는 제한적인 기본 파일 유지보수 작업입니다. 프로젝트는 안정적인 `projectKey`(Windows 대소문자 무시, 심볼릭 링크 해석)로 묶어 사이드바가 드라이브나 worktree 사이에서 이동하지 않게 합니다.
+- **모델 및 인증**: 엄격한 페이로드 검증(알 수 없는 형태 차단, 안전한 폴백)을 적용한 RPC 명령으로 omp 자식 프로세스와 통신합니다. Models 패널은 omp 에이전트 디렉터리의 `models.yml`을 편집하며 빈 자리 행을 제거하고 모호한 `enabledModels` 항목을 거부합니다.
+- **기본 설정**: General/MCP 설정 패널은 `~/.omp/agent/config.yml`(또는 `config.yaml` 폴백)의 허용 목록에 포함된 항목을 읽고 씁니다. 관련 없는 키와 주석은 보존하며 변경 사항은 새 세션과 재시작한 세션에 적용됩니다.
+- **스킬 및 플러그인**: omp 스킬 디렉터리(`~/.omp/agent/skills`, 프로젝트 `.omp/skills`, 호환 디렉터리)를 검색하고 플러그인 관리는 `omp plugin`을 호출합니다.
+- **MCP 서버**: 프로젝트 서버는 Git 최상위의 OMP 기본 위치(`.omp/mcp.json`, 이후 호환 파일)를 통해 관리하며 stdio/http/sse 스키마를 검증하고 원자적으로 기록합니다.
+- **파일 접근**: 파일 탐색과 미리보기는 선택한 프로젝트 디렉터리 및 세션에 나타난 작업 디렉터리로 제한됩니다. `isWindowsAbsolutePath`/`samePath` 단일 헬퍼로 경로를 정규화하고 `realpath` 해석 뒤 심볼릭 링크 탈출을 거부합니다. Windows에서는 루트에서 드라이브 목록을 제공하는 디렉터리 선택기를 사용합니다.
+- **포크와 세션 내 브랜치**: 포크는 새 `.jsonl` 파일을 만듭니다. “여기서 편집”은 같은 세션 파일 안에 다른 브랜치를 만듭니다.
+
+## 개발
+
+```bash
+npm install
+npm run dev
+```
+
+로컬 개발 서버는 [http://127.0.0.1:30178](http://127.0.0.1:30178)에서 실행됩니다.
+
+일반적인 검사:
+
+```bash
+npm run typecheck      # 타입 검사
+npm run lint           # ESLint(경고 0개 적용)
+npm test               # 테스트 스위트 실행
+npm run build          # 프로덕션 빌드
+```
+
+로컬 개발 중에는 `next build`/`npm run build`를 실행하지 마세요. `.next/`에 기록하여 개발 서버에 간섭할 수 있으므로 빌드는 릴리스 작업으로 남겨 두세요.
+
+## 국제화
+
+ompweb은 영어, 중국어 간체(简体中文), 일본어(日本語), 한국어(한국어)를 지원하며 모든 언어에서 전체 UI 문자열을 번역합니다. 언어는 `navigator.language`에서 자동 감지하고 상단 바의 언어 메뉴에서 실행 중 전환할 수 있습니다. 선택한 언어는 세션 간 유지됩니다.
+
+- 사전: `lib/i18n/locales/{en,zh-CN,ja,ko}.json`
+- 프레임워크: `lib/i18n/index.tsx` — `{var}` 보간과 복수형(`.one`/`.other`)을 지원하는 `useSyncExternalStore` 기반 경량 스토어
+- API 오류 메시지: 안정적인 오류 코드(`errors.<code>`)를 클라이언트에서 조회해 번역
+
+## 품질
+
+- **접근성**: WCAG AA 준수 — Lighthouse 접근성 점수 100/100, 전면 키보드 탐색, focus-visible 링, ARIA 역할
+- **성능**: 메모이제이션된 목록 컴포넌트, RAF로 제한한 스크롤/마우스 핸들러, 디바운스 검색, 스트리밍 JSONL 리더, ETag 캐시 세션 목록
+- **복원력**: omp 자식 프로세스의 정상 종료(프로세스 그룹 종료), 오류 경계, 원자적 세션 파일 재작성
+- **테스트**: 세션 파싱, 터미널 입력, Markdown 렌더링, 메시지 표시, 기본 설정, MCP 구성을 다루는 집중 테스트 스위트
+
+## 크레딧
+
+ompweb은 [earendil-works/pi](https://github.com/earendil-works/pi) pi 코딩 에이전트의 웹 UI인 [agegr/pi-web](https://github.com/agegr/pi-web)(MIT)을 포크하여 [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi)에 맞게 수정한 프로젝트입니다.
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,183 @@
+# ompweb
+
+[English](./README.md) | [한국어](./README.ko.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md)
+
+Local web UI for the [oh-my-pi (omp) coding agent](https://github.com/can1357/oh-my-pi). 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.
+
+![ompweb — light theme](docs/screenshot-light.png)
+
+<details>
+<summary>Dark theme</summary>
+
+![ompweb — dark theme](docs/screenshot-dark.png)
+
+</details>
+
+## Requirements
+
+- [omp](https://github.com/can1357/oh-my-pi) 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:**
+
+```bash
+npx ompgui@latest
+```
+
+**Or install globally:**
+
+```bash
+npm install -g ompgui
+ompweb
+```
+
+Then open [http://127.0.0.1:30177](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:**
+
+```bash
+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
+ompweb --password "a-long-random-password" # password-only sign-in without POSIX inline-env syntax
+
+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 # env-variable form (POSIX: inline or exported)
+OMP_WEB_NO_OPEN=1 ompweb        # useful when running as a background service
+
+# Windows (PowerShell / CMD)
+# $env:OMP_WEB_PASSWORD="a-long-random-password"; ompweb
+# or
+# ompweb --password "a-long-random-password"
+```
+
+Set `OMP_WEB_PASSWORD` (or pass `--password`) to protect the interface and every API endpoint with a themed, password-only sign-in screen. A successful sign-in creates an HTTP-only signed session cookie for 30 days; changing the configured password invalidates existing sessions. Leaving the variable unset disables authentication. Remote use still requires HTTPS through a trusted reverse proxy or VPN so the password and session cookie cannot be intercepted. On Windows the env-variable syntax is `$env:OMP_WEB_PASSWORD="..."`; `ompweb --password "..."` works in every shell without that extra step.
+
+## Remote & Mobile Access (Tailscale Recommended)
+
+For accessing `ompweb` from mobile devices (iPhone, iPad, Android) or external laptops, **using [Tailscale](https://tailscale.com/) is strongly recommended**. Tailscale creates a private, point-to-point WireGuard mesh VPN between your devices without exposing your host machine to the public internet or requiring port forwarding.
+
+### 1. Configure Password (Required for Remote Access)
+
+When binding to external network interfaces, setting a password is required to secure the workspace:
+
+```bash
+# CLI option: bind to all interfaces with a password
+ompweb -H 0.0.0.0 --password "your-strong-password"
+
+# Or via environment variables
+OMP_WEB_HOSTNAME=0.0.0.0 OMP_WEB_PASSWORD="your-strong-password" ompweb
+```
+
+### 2. Steps to Connect via Tailscale
+
+1. **Install Tailscale**: Download and sign into [Tailscale](https://tailscale.com/download) on both your host machine and your mobile device using the same account.
+2. **Start ompweb on your host machine**:
+   ```bash
+   ompweb --hostname 0.0.0.0 --password "your-strong-password"
+   ```
+3. **Access from your mobile browser**:
+   - Navigate to your host's Tailscale IP (e.g. `100.x.y.z`) or MagicDNS machine name:
+     ```text
+     http://100.x.y.z:30177
+     # Or with MagicDNS enabled:
+     http://my-macbook:30177
+     ```
+4. **Log in**: Enter your configured password to securely control and chat with your coding agent on mobile.
+
+### 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.
+- **Preview markdown faithfully**: YAML frontmatter renders in a summary card (title + key/value rows), math fences stay aligned inside lists, and CJK ranges like `5~7U` are no longer mangled (GFM now requires `~~` for strikethrough).
+- **Pick projects naturally on Windows**: a drive picker at the filesystem root and a case-folded, symlink-aware project identity keep the sidebar stable across drives and worktrees.
+- **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` / `--password` | Password for the sign-in screen; `--password` works in every shell (PowerShell/CMD) without ` $env:` syntax |
+| `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. Host env (`PORT`, `NEXT_*`, `NODE_ENV`) is stripped before spawn, and shutdown is graceful on both POSIX (process-group) and Windows (`taskkill /t`).
+- **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. Projects are grouped by a stable `projectKey` (Windows case-folded, symlink-resolved) so the sidebar doesn't jump between drives or worktrees.
+- **Models and auth**: RPC commands against the omp child process with strict payload validation (unknown-shape guards, safe fallbacks); the Models panel edits `models.yml` in the omp agent directory, dropping blank placeholder rows and rejecting ambiguous `enabledModels` entries.
+- **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; paths are canonicalized via a single `isWindowsAbsolutePath`/`samePath` helper and symlink escapes are rejected after `realpath` resolution. On Windows the directory picker offers a drive list at the root.
+- **Forks vs in-session branches**: Fork creates a new `.jsonl` file. "Edit from here" creates another branch inside the same session file.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+The local dev server runs at [http://127.0.0.1:30178](http://127.0.0.1:30178).
+
+Common checks:
+
+```bash
+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 (简体中文), Japanese (日本語), and Korean (한국어) with translated UI strings across all 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,ko}.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](https://github.com/agegr/pi-web) (MIT), the web UI for the [earendil/pi-mono](https://github.com/earendil-works/pi) pi coding agent, adapted for [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi).
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,169 @@
+# ompweb
+
+[English](./README.md) | [한국어](./README.ko.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md)
+
+[oh-my-pi (omp) 编程智能体](https://github.com/can1357/oh-my-pi)的本地 Web UI。ompweb 读取本机的 omp 会话文件，在浏览器中提供一个工作区，支持会话浏览、实时对话、模型配置、技能管理和项目文件预览。
+
+![ompweb — 浅色主题](docs/screenshot-light.png)
+
+<details>
+<summary>深色主题与命令面板</summary>
+
+![ompweb — 深色主题](docs/screenshot-dark.png)
+
+![ompweb — 命令面板](docs/screenshot-palette.png)
+
+</details>
+
+## 环境要求
+
+- 已安装 [omp](https://github.com/can1357/oh-my-pi) 且在 `PATH` 中（或通过 `OMP_WEB_OMP_BIN` 指向其二进制文件）
+- Node.js 22.19.0 或更高版本（`node --version`）
+
+## 快速开始
+
+**无需安装直接运行：**
+
+```bash
+npx ompgui@latest
+```
+
+**或全局安装：**
+
+```bash
+npm install -g ompgui
+ompweb
+```
+
+然后打开 [http://127.0.0.1:30177](http://127.0.0.1:30177)。服务器就绪后，CLI 会尝试自动打开浏览器。ompweb 默认监听 `127.0.0.1`。
+
+**选项：**
+
+```bash
+ompweb --port 8080              # 自定义端口
+ompweb --hostname 0.0.0.0       # 在可信网络中暴露服务
+ompweb -p 8080 -H 0.0.0.0       # 组合使用
+ompweb --no-open                # 不自动打开浏览器
+
+ompweb --password "a-long-random-password" # 启用仅密码登录（Windows 同样适用）
+
+PORT=8080 ompweb                # 也支持环境变量
+OMP_WEB_HOSTNAME=0.0.0.0 ompweb # 显式暴露到网络
+OMP_WEB_PASSWORD='a-long-random-password' ompweb # 环境变量形式（POSIX）
+# Windows: $env:OMP_WEB_PASSWORD="secret"; ompweb
+OMP_WEB_NO_OPEN=1 ompweb        # 作为后台服务运行时很有用
+```
+
+设置 `OMP_WEB_PASSWORD` 可通过与主题集成的仅密码登录页面保护界面和所有 API 端点。登录成功后，会创建有效期为 30 天的 HTTP-only 签名会话 Cookie；留空则关闭认证。远程访问仍需通过受信任反向代理或 VPN 提供 HTTPS，以保护密码和会话 Cookie。默认仅监听 `127.0.0.1`；不要将 ompweb 直接暴露到互联网。
+
+## 远程与移动端访问（推荐使用 Tailscale）
+
+从移动设备（iPhone、iPad、Android）或外部笔记本访问 `ompweb` 时，**强烈推荐使用 [Tailscale](https://tailscale.com/) 虚拟专用网（VPN）**。它通过端到端加密的点对点 Mesh 网络连接设备，无需端口转发或暴露公网 IP。
+
+### 1. 配置访问密码（远程访问必备）
+
+当绑定到外部网络接口时，必须配置密码以保护工作区：
+
+```bash
+# CLI 选项：绑定到所有网络接口并设置密码
+ompweb -H 0.0.0.0 --password "your-strong-password"
+
+# 或通过环境变量设置
+OMP_WEB_HOSTNAME=0.0.0.0 OMP_WEB_PASSWORD="your-strong-password" ompweb
+```
+
+### 2. Tailscale 连接步骤
+
+1. **安装 Tailscale**：在宿主电脑和移动设备上安装 [Tailscale](https://tailscale.com/download) 并登录同一账户。
+2. **在宿主电脑上启动 ompweb**：
+   ```bash
+   ompweb --hostname 0.0.0.0 --password "your-strong-password"
+   ```
+3. **在移动端浏览器中访问**：
+   - 访问宿主电脑的 Tailscale IP（如 `100.x.y.z`）或 MagicDNS 机器名：
+     ```text
+     http://100.x.y.z:30177
+     # 或启用 MagicDNS 时
+     http://my-macbook:30177
+     ```
+4. **登录**：输入设置的密码即可在移动设备上安全地与编程智能体进行实时交互与操作。
+
+## 功能特性
+
+- **随时接续之前的工作**：按项目浏览以往的 omp 对话，不必翻找终端历史或会话文件路径。
+- **放心尝试不同方向**：从更早的消息继续，或将会话分叉为一条独立路线。
+- **整理侧边栏**：归档不活跃会话而不删除原生记录，或在不再需要时明确删除。
+- **跨分支工作**：在侧边栏切换 Git 工作树，新会话和资源管理器都会跟随你选择的检出。
+- **边看项目边聊天**：左侧浏览文件，右侧预览源码、文档、图片、音频和 PDF，同时智能体继续工作。
+- **清晰掌握会话状态**：上下文用量、费用、压缩上下文状态和系统提示词详情都显示在顶栏。
+- **减少对终端配置的依赖**：在 Web UI 中管理模型、登录/API 密钥、模型测试、原生 OMP 控制（顾问、审批、Bash 策略、思考、压缩、记忆、自动学习、重试/回退）、技能、插件和项目 MCP 服务器。
+- **在设置中管理 MCP**：专用 MCP 标签页显示项目服务器状态（已启用 / 已禁用 / 无效），支持添加、编辑、重命名、校验和删除，并通过角落提示显示配置失败。
+- **保持 OMP 为最新版本**：可在设置中检查已安装运行时、更新它，并按需重启活动会话。
+- **及时获知完成状态**：可选择在智能体完成时接收浏览器通知，并检查已安装技能的更新。
+- **⌘K 随处跳转**：命令面板（⌘K / Ctrl+K）支持切换会话、新建会话和切换主题。
+- **温暖的纸感设计**：浅色/深色双主题，衬线展示字体，对比度经 WCAG AA 验证，基于令牌驱动的 UI 套件（Base UI 基元、cmdk、lucide 图标）构建。
+
+## 配置
+
+| 变量 | 含义 |
+| --- | --- |
+| `PORT` | 服务器端口（默认 `30177`；`-p/--port` 优先） |
+| `OMP_WEB_HOSTNAME` | 绑定主机名（默认 `127.0.0.1`；`-H/--hostname` 优先） |
+| `OMP_WEB_PASSWORD` | 登录页面使用的可选密码 |
+| `OMP_WEB_NO_OPEN` | 设为 `1`/`true` 可跳过自动打开浏览器 |
+| `OMP_WEB_OMP_BIN` | `omp` 不在 `PATH` 中时，指向其二进制文件的绝对路径 |
+| `PI_CODING_AGENT_DIR` | 指向其他 omp agent 目录（默认 `~/.omp/agent`） |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 服务器端请求使用的标准代理变量 |
+
+## 架构
+
+ompweb 是一个由 Node 托管的 Next.js 应用，驱动你已安装的 `omp` 二进制文件——它并不内嵌智能体：
+
+- **实时会话**：启动 `omp --mode rpc-ui`（基于 stdio 的 NDJSON），每个活动会话对应一个子进程，因此智能体版本始终与你安装的完全一致。
+- **会话浏览**：直接读取 omp 的会话文件（`~/.omp/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`）；标题、归档和删除是受保护的原生文件维护操作，不会与 OMP 的实时写入竞争。
+- **模型与认证**：通过 RPC 命令与 omp 子进程交互；模型面板编辑 omp agent 目录中的 `models.yml`。
+- **技能与插件**：扫描 omp 的技能目录（`~/.omp/agent/skills`、项目内 `.omp/skills` 及兼容目录），并调用 `omp plugin` 进行插件管理。
+- **文件访问**：文件浏览与预览仅限于所选项目目录以及会话中出现过的工作目录。
+- **分叉与会话内分支**：分叉会创建新的 `.jsonl` 文件；“从此处编辑”则在同一会话文件内创建另一个分支。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+本地开发服务器运行在 [http://127.0.0.1:30177](http://127.0.0.1:30177)。
+
+常用检查：
+
+```bash
+npx tsc --noEmit       # 类型检查
+npm run lint           # ESLint（零警告）
+node --test lib/*.test.mjs components/*.test.mjs   # 运行测试
+```
+
+本地开发时请避免运行 `next build` / `npm run build`。它会写入 `.next/`，可能干扰开发服务器；构建请留到发布阶段。
+
+## 多语言支持
+
+ompweb 支持英语、简体中文、日本語和韩语（한국어），四种语言均覆盖整个界面的翻译字符串。语言从 `navigator.language` 自动检测，可通过顶栏的语言菜单在运行时切换。选择会跨会话持久化。
+
+- 字典文件：`lib/i18n/locales/{en,zh-CN,ja,ko}.json`
+- 框架：`lib/i18n/index.tsx` — 基于 `useSyncExternalStore` 的轻量 store，支持 `{var}` 插值和复数形式（`.one`/`.other`）
+- API 错误消息通过稳定的错误码（`errors.<code>`）在客户端翻译
+
+## 质量
+
+- **可访问性**：符合 WCAG AA 标准 — Lighthouse 可访问性评分 100/100，全键盘导航，焦点可见环，ARIA 角色
+- **性能**：列表组件 memo 化、RAF 节流滚动/鼠标处理、防抖搜索、流式 JSONL 读取器、ETag 缓存会话列表
+- **健壮性**：优雅关闭 omp 子进程（进程组杀死）、错误边界、原子化会话文件重写
+- **测试**：聚焦的测试套件覆盖会话解析、终端输入、Markdown 渲染、消息展示、原生设置和 MCP 配置
+
+## 致谢
+
+ompweb 分叉自 [agegr/pi-web](https://github.com/agegr/pi-web)（MIT）——[badlogic/pi-mono](https://github.com/badlogic/pi-mono) pi 编程智能体的 Web UI，并针对 [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) 进行了适配。
+
+## 许可证
+
+MIT

package/bin/node-version.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const MIN_NODE_VERSION = "22.19.0";
+
+function parseNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return null;
+  return match.slice(1).map(Number);
+}
+
+function isNodeVersionSupported(version) {
+  const current = parseNodeVersion(version);
+  const minimum = parseNodeVersion(MIN_NODE_VERSION);
+  if (!current || !minimum) return false;
+
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (current[index] > minimum[index]) return true;
+    if (current[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+function getUnsupportedNodeVersionMessage(version) {
+  return [
+    `ompweb requires Node.js ${MIN_NODE_VERSION} or newer.`,
+    `Current Node.js version: ${version}.`,
+    "Upgrade Node.js and try again: https://nodejs.org/",
+  ].join("\n");
+}
+
+module.exports = {
+  MIN_NODE_VERSION,
+  getUnsupportedNodeVersionMessage,
+  isNodeVersionSupported,
+};

package/bin/omp-web-options.js

@@ -0,0 +1,86 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+
+function printHelp() {
+  console.log(`Usage: ompweb [options]
+
+Options:
+  -p, --port <port>        Server port (default 30177, env PORT)
+  -H, --hostname <host>    Bind hostname (default 127.0.0.1, env OMP_WEB_HOSTNAME)
+      --password <pass>    Password for the web sign-in screen (env OMP_WEB_PASSWORD)
+      --no-open            Do not open the browser automatically
+  -h, --help               Show this help
+      --version            Show version
+
+Password:
+  ompweb --password "a-long-random-password"
+  # env-variable forms (POSIX, PowerShell, CMD handled uniformly)
+  OMP_WEB_PASSWORD="secret" ompweb
+  $env:OMP_WEB_PASSWORD="secret"; ompweb   # PowerShell
+  set OMP_WEB_PASSWORD=secret&& ompweb     # CMD
+
+Security: use HTTPS via a trusted reverse proxy or VPN when binding to a
+non-loopback hostname, so the password and session cookie stay private.`);
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  const { values: cliArgs } = parseArgs({
+    args,
+    options: {
+      port:      { type: "string", short: "p" },
+      hostname:  { type: "string", short: "H" },
+      password:  { type: "string" },
+      help:      { type: "boolean", short: "h" },
+      version:   { type: "boolean" },
+      "no-open": { type: "boolean" },
+    },
+    strict: false,
+  });
+
+  // --password wins over env so Windows users without POSIX inline-env syntax have a first-class option.
+  const password = cliArgs.password ?? env.OMP_WEB_PASSWORD;
+  if (cliArgs.version) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const pkg = require("../package.json");
+      console.log(pkg.version ?? "0.0.0");
+    } catch { console.log("0.0.0"); }
+    return {
+      port: cliArgs.port ?? env.PORT ?? "30177",
+      hostname: cliArgs.hostname ?? env.OMP_WEB_HOSTNAME ?? "127.0.0.1",
+      password,
+      openBrowser: !cliArgs["no-open"] && !isEnabled(env.OMP_WEB_NO_OPEN),
+      version: true,
+    };
+  }
+  // Expose help flag without exiting here — caller (bin/omp-web.js) decides
+  // whether to exit, keeping parseLaunchOptions testable. Print here so
+  // --help works even when the caller is a test.
+  if (cliArgs.help) {
+    printHelp();
+    return {
+      port: cliArgs.port ?? env.PORT ?? "30177",
+      hostname: cliArgs.hostname ?? env.OMP_WEB_HOSTNAME ?? "127.0.0.1",
+      password,
+      openBrowser: !cliArgs["no-open"] && !isEnabled(env.OMP_WEB_NO_OPEN),
+      help: true,
+    };
+  }
+  return {
+    port: cliArgs.port ?? env.PORT ?? "30177",
+    hostname: cliArgs.hostname ?? env.OMP_WEB_HOSTNAME ?? "127.0.0.1",
+    password,
+    openBrowser: !cliArgs["no-open"] && !isEnabled(env.OMP_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseLaunchOptions };