11 KiB
概要
PiAgentUI は Pi coding agent 用のチャット UI 兼 workspace です。Pi 拡張機能が配信する Web アプリとして、または Tauri 2 のデスクトップアプリとして動き、素のターミナルでは見えないもの（セッション一覧、tool call、MCP サーバー、skills、コンテキスト使用量）を 1 つのウィンドウにまとめます。
- 実際の Pi セッションを SSE（
/global/event）でストリーミングし、Markdown、コード（Shiki）、数式（KaTeX）を描画します。 - tool call をカードで表示し、アクティブなセッションのコンテキスト使用量を表示します。
- ランタイムが返す capability を使ってモデルを切り替えます。
- 設定済みの MCP サーバー（transport、command、URL、source）と、source ごとにまとめた有効な skills を一覧表示します。
- 組み込みと動的な slash command、composer の Git 操作を提供します。
- チャットの横にターミナル（xterm.js）とファイルエクスプローラーを組み込んでいます。
- settings で指定した OpenAI 互換の STT エンドポイント経由で音声入力を受け付けます。
- UI の言語:
en,pt-BR,es,zh-CN,hi,bn,ar（src/locales/）。日本語の UI はまだありません。
使う理由
PiAgentUI はエージェントの状態を独自に持ちません。セッション、モデル、tools、skills、コマンドは拡張機能を通じて Pi ランタイムから取得するので、画面に出るものは Pi が実際に動かしているものです。
Pi を使っていないなら向きません。拡張機能がないと、UI はサーバー接続ダイアログしか表示しません。また 1 ウィンドウにつき 1 ランタイムで、ホストされたデモや npm 公開パッケージもありません。
仕組み
extensions/piagentui-server.tsが Pi 拡張機能です。Node のhttp+wsでdist/のビルド済み UI を配信し、window.PI_BOOT_DATA（ベース URL とトークン）を注入します。- 起動時にポート
58785（使用中なら次の空きポート）で待ち受け、ポートとランダムなトークンを~/.pi/agent/piagentui-port.jsonに書き込みます。 GET /global/healthは認証なしで、ほかの/api/*ルートはAuthorization: Bearer <token>が必要です。ソケットは0.0.0.0にバインドしますが、/api/network/accessの LAN アクセスが有効（デフォルトは無効）でない限り、各リクエストは loopback かどうか検査されます。- Tauri アプリは
get_pi_agent_connectionコマンドで同じ discovery ファイルを読むため、デスクトップ版は手動設定なしでローカルのランタイムに接続します。 - コンテナでは、Rust の router（
src-router/、axum）が Caddy の背後で gateway として frontend と backend の前に立ちます。
クイックスタート
| ツール | バージョン | 用途 |
|---|---|---|
| Node.js | >=22（.tool-versions: 22.22.0） |
すべて |
| npm | Node に同梱のもの | すべて（package-lock.json） |
| Rust | 1.85.0（.tool-versions） |
デスクトップアプリと gateway の router |
| Docker Compose | 最近のもの | コンテナ構成のみ |
| Pi Agent | ローカルにインストール済み | 実際のセッションとモデル |
git clone https://git.evandro.dev.br/evandro/PiAgentUI.git
cd PiAgentUI
npm ci # postinstall で scripts/copy-material-icons.mjs が動きます
npm run build # tsc -b && vite build -> dist/
npm run dev # Vite 開発サーバー http://localhost:5173
npm run dev はフロントエンドのみで、/api をプレフィックスを外して 127.0.0.1:4096 にプロキシします。Pi で使う場合は先にビルドし、拡張機能に dist/ を配信させます（Pi は package.json の pi.extensions フィールドでこのリポジトリをパッケージとして読み込みます）。
npm run build
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
# http://127.0.0.1:58785 を開く
デスクトップと Android:
npm run tauri dev # Vite 開発サーバー上のデスクトップウィンドウ
npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json)
npm run tauri android dev # scripts/dev-android.sh を参照
PR の前に npm run validate を実行してください。typecheck、拡張機能の typecheck、lint、build、テストを順に実行し、CI の build.yml もこれを使います。
設定
コンテナ構成は OpenCodeUI のデプロイから引き継いだものです。最初に .env.example を .env にコピーしてください。
| ファイル | コマンド | 内容 |
|---|---|---|
docker-compose.yml |
docker compose up -d |
フル構成: gateway（Caddy + Rust router、127.0.0.1:6658 と 6659）、frontend、backend（opencode serve、4096、メモリ上限 4G）。 |
docker-compose.standalone.yml |
docker compose -f docker-compose.standalone.yml up -d |
既存の opencode serve 向けのフロントエンドのみ。BACKEND_URL（デフォルト host.docker.internal:4096）と PORT（デフォルト 3000）を使います。 |
docker-compose.host.yml |
docker compose -f docker-compose.yml -f docker-compose.host.yml up -d |
任意の override: backend を privileged で動かし、Docker ソケットとホストの / を /host にマウントします。 |
docker-compose.build.yml |
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build |
任意の override: docker/ から gateway、frontend、backend をローカルでビルドします。 |
環境変数（コンテナ構成のみ）
| 変数 | 必須 | 説明 |
|---|---|---|
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, XAI_API_KEY |
最低 1 つ | backend コンテナに渡す LLM プロバイダーのキー。 |
GATEWAY_PORT |
いいえ（6658） |
統合エントリーポイントのホスト側ポート。 |
PREVIEW_PORT |
いいえ（6659） |
プレビュー用エントリーポイントのホスト側ポート。 |
PREVIEW_DOMAIN |
いいえ | プレビュー用の別ドメイン。リバースプロキシが PREVIEW_PORT に転送します。 |
WORKSPACE |
いいえ（./workspace） |
backend の /workspace にマウントするホストのディレクトリ。 |
OPENCODE_SERVER_PASSWORD |
公開デプロイ時 | backend と router のパスワード。 |
OPENCODE_SERVER_USERNAME |
いいえ（opencode） |
上記パスワードと組になるユーザー名。 |
PUBLIC_BASE_URL |
いいえ | gateway 内蔵の router が使う公開ベース URL。 |
ROUTER_SCAN_INTERVAL |
いいえ（5） |
router のスキャン間隔。 |
ROUTER_TOKEN_LENGTH |
いいえ（12） |
生成するルートトークンの長さ。 |
ROUTER_PORT_RANGE |
いいえ（3000-9999） |
router が扱うポート範囲。 |
ROUTER_EXCLUDE_PORTS |
いいえ（4096） |
router が除外するポート。 |
DOCKER_API_VERSION |
いいえ（1.40） |
backend が使う Docker API のバージョン。.env.example ではなく docker-compose.yml で設定されています。 |
USE_CHINA_MIRROR |
いいえ（1） |
backend イメージのビルドオプション。下のミラーを使います。 |
APT_MIRROR, APT_SECURITY_MIRROR, NPM_CONFIG_REGISTRY, NODEJS_ORG_MIRROR, PIP_INDEX_URL, PIP_TRUSTED_HOST |
いいえ | backend のツールチェーン用ミラー。 |
MISE_INSTALL_URL, OPENCODE_INSTALL_URL |
いいえ | backend イメージのビルドで使うインストーラーの URL。 |
プロジェクトの状態
1.0 前のベータ版（0.6.10）で、開発者 1 人がメンテナンスしています。リリースは v* タグで release.yml がビルドし（Windows、macOS、Linux、Android の成果物）、deploy.yml が VITE_BASE_PATH=/PiAgentUI/ で Web 版を公開します。
- OpenCodeUI の名前はまだ一部に残っています。Rust router の crate は
opencodeui-router、イメージはopencodeui-*、Android の APK はOpenCodeUI-*、.env.exampleのコメントは中国語で、Docker の backend が動かすopencode serveは Pi 拡張機能のフローではなく引き継いだデプロイのものです。 docker-compose.ymlとdocker-compose.standalone.ymlは、まだ upstream のghcr.io/lehhair/opencodeui-frontendイメージを取得します。- テストはコンポーネントとサーバーのレベル（Vitest）です。Tauri シェルと Rust router はコンパイル以外のテストがなく、ブラウザの end-to-end テストもカバレッジの閾値もありません。
- 音声入力には OpenAI 互換の STT エンドポイントが必要で、ブラウザでの自動テストはありません。
Issue と pull request は issue tracker へ。PR の前に npm run validate を実行してください。
ライセンス
GPL-3.0-only。LICENSE を参照してください。PiAgentUI は OpenCodeUI をフォークして作り直したもので、元の作者は src-tauri/Cargo.toml に記載されています。