PiAgentUI: workspace desktop e web para sessões reais do Pi Agent, com chat, cards de tool calls e o painel Files, Changes, MCP e 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) ![Licença GPL-3.0-only](https://img.shields.io/badge/licen%C3%A7a-GPL--3.0--only-blue?style=flat-square) ![Status beta 0.6.10](https://img.shields.io/badge/status-beta%200.6.10-yellow?style=flat-square) [Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [Specs de design](docs/superpowers/specs/) [English](README.md) · **Português (BR)** · [Español](README.es.md) · [日本語](README.ja.md)
![Workspace de chat do PiAgentUI: lista de sessões à esquerda, resposta em Markdown com bloco JSON no centro e o painel de servidores MCP à direita](src/assets/images/img1.png) ## O que é PiAgentUI é uma interface de chat e um workspace para o [agente de código Pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent). Roda como app web servido por uma extensão do Pi ou como app desktop em Tauri 2, e mostra numa janela o que o terminal cru esconde: a lista de sessões, as tool calls, os servidores MCP, as skills e o uso de contexto. - Faz streaming das sessões reais do Pi por SSE (`/global/event`) e renderiza Markdown, código (Shiki) e matemática (KaTeX). - Mostra tool calls como cards e o uso de contexto da sessão ativa. - Troca de modelo usando as capacidades que o runtime informa. - Lista os servidores MCP configurados (transporte, comando, URL, origem) e as skills efetivas agrupadas por origem. - Expõe slash commands nativos e dinâmicos, além de controles de Git no composer. - Embute um terminal (xterm.js) e um explorador de arquivos ao lado do chat. - Aceita entrada de voz por um endpoint de STT compatível com OpenAI configurado nas settings. - Idiomas da interface: `en`, `pt-BR`, `es`, `zh-CN`, `hi`, `bn`, `ar` (`src/locales/`). ## Por que usar O PiAgentUI não guarda estado próprio do agente. Sessões, modelos, tools, skills e comandos vêm do runtime do Pi pela extensão, então o que aparece na tela é o que o Pi está rodando. Não use se você não roda o Pi: sem a extensão, a interface mostra só o diálogo de conexão com o servidor. Ele também atende um runtime por janela e não tem demo hospedada nem pacote publicado no npm. ## Como funciona - `extensions/piagentui-server.ts` é a extensão do Pi. Ela serve a UI compilada de `dist/` com `http` + `ws` do Node e injeta `window.PI_BOOT_DATA` (URL base e token). - Ao iniciar, escuta na porta `58785` (ou na próxima livre) e grava a porta e um token aleatório em `~/.pi/agent/piagentui-port.json`. - `GET /global/health` é aberto; as outras rotas `/api/*` exigem `Authorization: Bearer `. O socket escuta em `0.0.0.0`, mas cada requisição é checada contra loopback, a menos que o acesso pela LAN em `/api/network/access` esteja ligado (vem desligado). - O app Tauri lê o mesmo arquivo de descoberta pelo comando `get_pi_agent_connection`, então o build desktop conecta no runtime local sem configuração manual. - Em containers, o router em Rust (`src-router/`, axum) fica atrás do Caddy como gateway na frente dos serviços de frontend e backend. ## Início rápido | Ferramenta | Versão | Usada para | |---|---|---| | Node.js | `>=22` (`.tool-versions`: 22.22.0) | tudo | | npm | a que vem com o Node | tudo (`package-lock.json`) | | Rust | `1.85.0` (`.tool-versions`) | app desktop e router do gateway | | Docker Compose | recente | só a stack em containers | | Pi Agent | instalado localmente | sessões e modelos reais | ```bash git clone https://git.evandro.dev.br/evandro/PiAgentUI.git cd PiAgentUI npm ci # o postinstall roda scripts/copy-material-icons.mjs npm run build # tsc -b && vite build -> dist/ npm run dev # servidor Vite em http://localhost:5173 ``` `npm run dev` é só o front end: ele faz proxy de `/api` para `127.0.0.1:4096` sem o prefixo. Para o fluxo com o Pi, compile antes e deixe a extensão servir `dist/` (o Pi carrega este repositório como pacote pelo campo `pi.extensions` do `package.json`): ```bash npm run build cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."} # abra http://127.0.0.1:58785 ``` Desktop e Android: ```bash npm run tauri dev # janela desktop sobre o servidor Vite npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json) npm run tauri android dev # veja scripts/dev-android.sh ``` Antes de um PR, `npm run validate` roda typecheck, typecheck da extensão, lint, build e testes; é o gate que o CI roda em `build.yml`. ## Configuração A stack em containers foi herdada do deploy do OpenCodeUI. Copie `.env.example` para `.env` antes. | Arquivo | Comando | O que faz | |---|---|---| | `docker-compose.yml` | `docker compose up -d` | Stack completa: `gateway` (Caddy + router em Rust, `127.0.0.1:6658` e `6659`), `frontend`, `backend` (`opencode serve`, 4096, limite de 4G de memória). | | `docker-compose.standalone.yml` | `docker compose -f docker-compose.standalone.yml up -d` | Só o front end, para um `opencode serve` já existente. Usa `BACKEND_URL` (padrão `host.docker.internal:4096`) e `PORT` (padrão `3000`). | | `docker-compose.host.yml` | `docker compose -f docker-compose.yml -f docker-compose.host.yml up -d` | Override opcional: o `backend` roda privilegiado, com o socket do Docker e o `/` do host montado em `/host`. | | `docker-compose.build.yml` | `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` | Override opcional: compila gateway, frontend e backend localmente a partir de `docker/`. |
Variáveis de ambiente (só para a stack em containers) | Variável | Obrigatória | Descrição | |---|---|---| | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY` | Ao menos uma | Chaves de provedores de LLM repassadas ao container do backend. | | `GATEWAY_PORT` | Não (`6658`) | Porta do host para o ponto de entrada unificado. | | `PREVIEW_PORT` | Não (`6659`) | Porta do host para o ponto de entrada de previews. | | `PREVIEW_DOMAIN` | Não | Domínio separado para previews; o proxy reverso encaminha para `PREVIEW_PORT`. | | `WORKSPACE` | Não (`./workspace`) | Pasta do host montada em `/workspace` no backend. | | `OPENCODE_SERVER_PASSWORD` | Em deploys públicos | Senha do backend e do router. | | `OPENCODE_SERVER_USERNAME` | Não (`opencode`) | Usuário que acompanha a senha acima. | | `PUBLIC_BASE_URL` | Não | URL base pública usada pelo router embutido no gateway. | | `ROUTER_SCAN_INTERVAL` | Não (`5`) | Intervalo de varredura do router. | | `ROUTER_TOKEN_LENGTH` | Não (`12`) | Tamanho dos tokens de rota gerados. | | `ROUTER_PORT_RANGE` | Não (`3000-9999`) | Faixa de portas que o router atende. | | `ROUTER_EXCLUDE_PORTS` | Não (`4096`) | Portas que o router ignora. | | `DOCKER_API_VERSION` | Não (`1.40`) | Versão da API do Docker para o backend; definida no `docker-compose.yml`, não no `.env.example`. | | `USE_CHINA_MIRROR` | Não (`1`) | Opção de build da imagem do backend: usa os mirrors abaixo. | | `APT_MIRROR`, `APT_SECURITY_MIRROR`, `NPM_CONFIG_REGISTRY`, `NODEJS_ORG_MIRROR`, `PIP_INDEX_URL`, `PIP_TRUSTED_HOST` | Não | Mirrors para o toolchain do backend. | | `MISE_INSTALL_URL`, `OPENCODE_INSTALL_URL` | Não | URLs de instalação usadas no build da imagem do backend. |
## Estado do projeto Beta, antes da 1.0 (`0.6.10`), mantido por um desenvolvedor. As releases saem do `release.yml` em tags `v*` (artefatos para Windows, macOS, Linux e Android); o `deploy.yml` publica o build web com `VITE_BASE_PATH=/PiAgentUI/`. - O nome OpenCodeUI ainda não saiu de tudo: o crate do router em Rust é `opencodeui-router`, as imagens são `opencodeui-*`, os APKs Android saem como `OpenCodeUI-*`, os comentários do `.env.example` estão em chinês e o backend Docker roda `opencode serve`, que é do deploy herdado, não do fluxo com a extensão do Pi. - `docker-compose.yml` e `docker-compose.standalone.yml` ainda puxam a imagem upstream `ghcr.io/lehhair/opencodeui-frontend`. - Os testes são de componente e de servidor (Vitest). Não há testes do shell Tauri nem do router em Rust além da compilação, nem teste end-to-end no navegador, nem meta de cobertura. - A entrada de voz depende de um endpoint de STT compatível com OpenAI e não tem teste automatizado no navegador. Issues e pull requests vão para o [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues); rode `npm run validate` antes de abrir um PR. ## Licença GPL-3.0-only, veja [`LICENSE`](LICENSE). O PiAgentUI é um fork retrabalhado do OpenCodeUI; o autor original está creditado em `src-tauri/Cargo.toml`. ---
Feito por Evandro Fonseca Junior · git.evandro.dev.br