PiAgentUI: workspace de escritorio y web para sesiones reales de Pi Agent, con chat, tarjetas de tool calls y el panel Files, Changes, MCP y Skills ![TypeScript 5.9](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white) ![React 19](https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black) ![Tauri 2](https://img.shields.io/badge/Tauri-2-24C8DB?style=flat-square&logo=tauri&logoColor=white) ![Licencia GPL-3.0-only](https://img.shields.io/badge/licencia-GPL--3.0--only-blue?style=flat-square) ![Estado beta 0.6.10](https://img.shields.io/badge/estado-beta%200.6.10-yellow?style=flat-square) [Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [Specs de diseño](docs/superpowers/specs/) [English](README.md) · [Português (BR)](README.pt-BR.md) · **Español** · [日本語](README.ja.md)
![Workspace de chat de PiAgentUI: lista de sesiones a la izquierda, una respuesta en Markdown con un bloque JSON en el centro y el panel de servidores MCP a la derecha](src/assets/images/img1.png) ## Qué es PiAgentUI es una interfaz de chat y un workspace para el [agente de código Pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent). Funciona como app web servida por una extensión de Pi o como app de escritorio con Tauri 2, y muestra en una ventana lo que una terminal sola esconde: la lista de sesiones, las tool calls, los servidores MCP, las skills y el uso de contexto. - Transmite sesiones reales de Pi por SSE (`/global/event`) y renderiza Markdown, código (Shiki) y matemáticas (KaTeX). - Muestra las tool calls como tarjetas y el uso de contexto de la sesión activa. - Cambia de modelo con las capacidades que informa el runtime. - Lista los servidores MCP configurados (transporte, comando, URL, origen) y las skills efectivas agrupadas por origen. - Expone slash commands integrados y dinámicos, además de controles de Git en el composer. - Integra una terminal (xterm.js) y un explorador de archivos junto al chat. - Acepta entrada de voz mediante un endpoint STT compatible con OpenAI configurado en settings. - Idiomas de la interfaz: `en`, `pt-BR`, `es`, `zh-CN`, `hi`, `bn`, `ar` (`src/locales/`). ## Por qué usarlo PiAgentUI no guarda estado propio del agente. Sesiones, modelos, tools, skills y comandos vienen del runtime de Pi a través de la extensión, así que lo que ves es lo que Pi está ejecutando. No lo uses si no ejecutas Pi: sin la extensión, la interfaz solo muestra el diálogo de conexión al servidor. También atiende un runtime por ventana y no tiene demo alojada ni paquete publicado en npm. ## Cómo funciona - `extensions/piagentui-server.ts` es la extensión de Pi. Sirve la UI compilada desde `dist/` con `http` + `ws` de Node e inyecta `window.PI_BOOT_DATA` (URL base y token). - Al arrancar escucha en el puerto `58785` (o el siguiente libre) y escribe el puerto y un token aleatorio en `~/.pi/agent/piagentui-port.json`. - `GET /global/health` es abierto; las demás rutas `/api/*` exigen `Authorization: Bearer `. El socket escucha en `0.0.0.0`, pero cada petición se valida contra loopback salvo que el acceso por LAN en `/api/network/access` esté activado (viene desactivado). - La app Tauri lee el mismo archivo de descubrimiento con el comando `get_pi_agent_connection`, así que el build de escritorio se conecta al runtime local sin configuración manual. - En contenedores, el router en Rust (`src-router/`, axum) va detrás de Caddy como gateway delante de los servicios de frontend y backend. ## Inicio rápido | Herramienta | Versión | Necesaria para | |---|---|---| | Node.js | `>=22` (`.tool-versions`: 22.22.0) | todo | | npm | la que trae Node | todo (`package-lock.json`) | | Rust | `1.85.0` (`.tool-versions`) | app de escritorio y router del gateway | | Docker Compose | reciente | solo el stack de contenedores | | Pi Agent | instalado localmente | sesiones y modelos reales | ```bash git clone https://git.evandro.dev.br/evandro/PiAgentUI.git cd PiAgentUI npm ci # el postinstall ejecuta scripts/copy-material-icons.mjs npm run build # tsc -b && vite build -> dist/ npm run dev # servidor Vite en http://localhost:5173 ``` `npm run dev` es solo el front end: hace proxy de `/api` a `127.0.0.1:4096` sin el prefijo. Para el flujo con Pi, compila primero y deja que la extensión sirva `dist/` (Pi carga este repositorio como paquete mediante el campo `pi.extensions` de `package.json`): ```bash npm run build cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."} # abre http://127.0.0.1:58785 ``` Escritorio y Android: ```bash npm run tauri dev # ventana de escritorio sobre el servidor Vite npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json) npm run tauri android dev # ver scripts/dev-android.sh ``` Antes de un PR, `npm run validate` ejecuta typecheck, typecheck de la extensión, lint, build y tests; es el gate que corre el CI en `build.yml`. ## Configuración El stack de contenedores viene heredado del despliegue de OpenCodeUI. Copia `.env.example` a `.env` primero. | Archivo | Comando | Qué hace | |---|---|---| | `docker-compose.yml` | `docker compose up -d` | Stack completo: `gateway` (Caddy + router en Rust, `127.0.0.1:6658` y `6659`), `frontend`, `backend` (`opencode serve`, 4096, límite de 4G de memoria). | | `docker-compose.standalone.yml` | `docker compose -f docker-compose.standalone.yml up -d` | Solo el front end, para un `opencode serve` existente. Usa `BACKEND_URL` (por defecto `host.docker.internal:4096`) y `PORT` (por defecto `3000`). | | `docker-compose.host.yml` | `docker compose -f docker-compose.yml -f docker-compose.host.yml up -d` | Override opcional: el `backend` corre privilegiado, con el socket de Docker y el `/` del host montado en `/host`. | | `docker-compose.build.yml` | `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` | Override opcional: compila gateway, frontend y backend localmente desde `docker/`. |
Variables de entorno (solo para el stack de contenedores) | Variable | Obligatoria | Descripción | |---|---|---| | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY` | Al menos una | Claves de proveedores de LLM que se pasan al contenedor del backend. | | `GATEWAY_PORT` | No (`6658`) | Puerto del host para el punto de entrada unificado. | | `PREVIEW_PORT` | No (`6659`) | Puerto del host para el punto de entrada de previews. | | `PREVIEW_DOMAIN` | No | Dominio aparte para previews; el proxy inverso lo reenvía a `PREVIEW_PORT`. | | `WORKSPACE` | No (`./workspace`) | Carpeta del host montada en `/workspace` en el backend. | | `OPENCODE_SERVER_PASSWORD` | En despliegues públicos | Contraseña del backend y del router. | | `OPENCODE_SERVER_USERNAME` | No (`opencode`) | Usuario que acompaña a la contraseña anterior. | | `PUBLIC_BASE_URL` | No | URL base pública que usa el router integrado en el gateway. | | `ROUTER_SCAN_INTERVAL` | No (`5`) | Intervalo de escaneo del router. | | `ROUTER_TOKEN_LENGTH` | No (`12`) | Longitud de los tokens de ruta generados. | | `ROUTER_PORT_RANGE` | No (`3000-9999`) | Rango de puertos que atiende el router. | | `ROUTER_EXCLUDE_PORTS` | No (`4096`) | Puertos que el router omite. | | `DOCKER_API_VERSION` | No (`1.40`) | Versión de la API de Docker para el backend; se define en `docker-compose.yml`, no en `.env.example`. | | `USE_CHINA_MIRROR` | No (`1`) | Opción de build de la imagen del backend: usa los mirrors de abajo. | | `APT_MIRROR`, `APT_SECURITY_MIRROR`, `NPM_CONFIG_REGISTRY`, `NODEJS_ORG_MIRROR`, `PIP_INDEX_URL`, `PIP_TRUSTED_HOST` | No | Mirrors para el toolchain del backend. | | `MISE_INSTALL_URL`, `OPENCODE_INSTALL_URL` | No | URLs de instalación usadas al compilar la imagen del backend. |
## Estado del proyecto Beta, antes de la 1.0 (`0.6.10`), mantenido por un desarrollador. Las releases salen de `release.yml` en tags `v*` (artefactos para Windows, macOS, Linux y Android); `deploy.yml` publica el build web con `VITE_BASE_PATH=/PiAgentUI/`. - El nombre OpenCodeUI no ha desaparecido del todo: el crate del router en Rust es `opencodeui-router`, las imágenes son `opencodeui-*`, los APK de Android salen como `OpenCodeUI-*`, los comentarios de `.env.example` están en chino y el backend Docker ejecuta `opencode serve`, que pertenece al despliegue heredado, no al flujo con la extensión de Pi. - `docker-compose.yml` y `docker-compose.standalone.yml` todavía descargan la imagen upstream `ghcr.io/lehhair/opencodeui-frontend`. - Los tests son de componente y de servidor (Vitest). No hay tests del shell Tauri ni del router en Rust más allá de la compilación, ni test end-to-end en navegador, ni umbral de cobertura. - La entrada de voz necesita un endpoint STT compatible con OpenAI y no tiene test automatizado en navegador. Issues y pull requests van al [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues); ejecuta `npm run validate` antes de abrir un PR. ## Licencia GPL-3.0-only, ver [`LICENSE`](LICENSE). PiAgentUI es un fork reelaborado de OpenCodeUI; el autor original figura en `src-tauri/Cargo.toml`. ---
Hecho por Evandro Fonseca Junior · git.evandro.dev.br