evandro/PiAgentUI
1
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): redesenha o README com hero em SVG [skip ci]

Browse Source
This commit is contained in:
evandro committed 2026-10-24 04:57:55 -03:00
1 parent 8ce05620e0
commit 13b464b4d6
5 files changed
+403 -647
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+70 -132
View File
@@ -1,198 +1,136 @@
<div align="center">
<img src="./assets/app-icons/app-icon.svg" width="96" alt="PiAgentUI logo" />
<img src="assets/readme/hero.svg" width="100%" alt="PiAgentUI: a desktop and web workspace for live Pi Agent sessions, with chat, tool call cards and the Files, Changes, MCP and Skills panel">
<h1>PiAgentUI</h1>
![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)
![License GPL-3.0-only](https://img.shields.io/badge/license-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)
<p><strong>Desktop and web workspace for AI coding agents: streams real Pi Agent sessions with chat, tool cards, MCP and skills panels.</strong></p>
[Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [Design specs](docs/superpowers/specs/)
<a href="#-quickstart">Quickstart</a> ·
<a href="#-architecture">Architecture</a> ·
<a href="#-documentation">Docs</a> ·
<a href="https://git.evandro.dev.br/evandro/PiAgentUI/issues">Issues</a>
![Stack](https://img.shields.io/badge/Stack-Tauri%20%2B%20TypeScript-24C8DB?logo=tauri&logoColor=white)
![Status](https://img.shields.io/badge/status-beta%200.6.10-yellow)
![License](https://img.shields.io/badge/license-GPL--3.0--only-green)
**English (US)** | [Português (BR)](./README.pt-BR.md) | [Español](./README.es.md) | [日本語](./README.ja.md)
**English** · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · [日本語](README.ja.md)
</div>
<hr />
![PiAgentUI chat workspace: session list on the left, a Markdown answer with a JSON block in the middle and the MCP servers panel on the right](src/assets/images/img1.png)
## 📌 The problem
## What it is
Pi Agent runs in a terminal. A bare terminal gives you no overview of sessions, no readable tool calls, and no place to inspect MCP servers, skills or context usage. PiAgentUI puts those in one window, as a web app or a Tauri desktop app, without inventing agent state: sessions, models, tools, skills and commands come from the Pi runtime whenever possible.
PiAgentUI is a chat UI and workspace for the [Pi coding agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent). It runs as a web app served by a Pi extension or as a Tauri 2 desktop app, and shows in one window what a bare terminal hides: the session list, tool calls, MCP servers, skills and context usage.
## ✨ What it does
- Streams real Pi Agent sessions into a chat view over SSE (`/global/event`), with Markdown, code highlighting (Shiki) and math (KaTeX).
- Renders tool calls as cards and shows context usage for the active session.
- Switches models, using the normalized capabilities returned by the runtime.
- Streams real Pi sessions over SSE (`/global/event`) and renders Markdown, code (Shiki) and math (KaTeX).
- Shows tool calls as cards and the context usage of the active session.
- Switches models using the capabilities the runtime reports.
- Lists configured MCP servers (transport, command, URL, source) and effective skills grouped by source.
- Exposes built-in and dynamic slash commands, plus Git controls in the composer.
- Embeds a terminal (xterm.js) and a file explorer next to the chat.
- Accepts voice input through an OpenAI-compatible STT endpoint configured in settings.
- Ships as a web build or a Tauri 2 app, with UI locales `en`, `pt-BR`, `es`, `ja`, `zh-CN`, `hi`, `bn` and `ar`.
- Accepts voice input through an OpenAI-compatible STT endpoint set in settings.
- UI locales: `en`, `pt-BR`, `es`, `zh-CN`, `hi`, `bn`, `ar` (`src/locales/`).
## 🚀 Quickstart
## Why use it
| Tool | Minimum version | Needed for |
PiAgentUI does not keep its own agent state. Sessions, models, tools, skills and commands come from the Pi runtime through the extension, so what you see is what Pi is running.
Do not use it if you do not run Pi: without the extension the UI only shows the server connection dialog. It also handles one runtime per window and has no hosted demo or published npm package.
## How it works
- `extensions/piagentui-server.ts` is the Pi extension. It serves the built UI from `dist/` over Node `http` + `ws` and injects `window.PI_BOOT_DATA` (base URL and token).
- On start it listens on port `58785` (or the next free one) and writes the port and a random token to `~/.pi/agent/piagentui-port.json`.
- `GET /global/health` is open; other `/api/*` routes require `Authorization: Bearer <token>`. The socket binds `0.0.0.0`, but each request is checked against loopback unless the LAN toggle at `/api/network/access` is on (off by default).
- The Tauri app reads the same discovery file through `get_pi_agent_connection`, so the desktop build connects to the local runtime without manual setup.
- In containers, the Rust router (`src-router/`, axum) sits behind Caddy as the gateway in front of the frontend and backend services.
## Quickstart
| Tool | Version | Needed for |
|---|---|---|
| Node.js | `>=22` (`.tool-versions`: 22.22.0) | everything |
| npm | `>=10` | everything (`package-lock.json` is authoritative) |
| Rust | `1.85.0` (`src-tauri/Cargo.toml`) | desktop app and gateway router only |
| Docker | Docker Compose | container stack only |
| npm | bundled with Node | everything (`package-lock.json`) |
| Rust | `1.85.0` (`.tool-versions`) | desktop app and gateway router |
| Docker Compose | any recent | container stack only |
| Pi Agent | installed locally | real sessions and models |
Without Pi Agent the UI starts in standalone mode and only shows the server connection dialog.
```bash
git clone https://git.evandro.dev.br/evandro/PiAgentUI.git
cd PiAgentUI
npm ci # postinstall runs scripts/copy-material-icons.mjs
npm run build # tsc -b && vite build -> dist/
npm run dev # Vite dev server on http://localhost:5173
npm ci # postinstall runs scripts/copy-material-icons.mjs
npm run build # tsc -b && vite build -> dist/
npm run dev # Vite dev server on http://localhost:5173
```
`npm run dev` is front-end only: it proxies `/api` to `127.0.0.1:4096` with the prefix stripped. For the Pi flow, build first and let the extension serve `dist/`:
`npm run dev` is front end only: it proxies `/api` to `127.0.0.1:4096` with the prefix stripped. For the Pi flow, build first and let the extension serve `dist/` (Pi loads this repository as a package through the `pi.extensions` field of `package.json`):
```bash
npm run build
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
# open http://127.0.0.1:58785 (Pi Agent running this repo as a Pi package, see package.json "pi")
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
# open http://127.0.0.1:58785
```
Desktop and Android:
```bash
npm run tauri dev # desktop window on the Vite dev server
npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json)
npm run tauri android dev # see scripts/dev-android.sh
npm run tauri dev # desktop window on the Vite dev server
npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json)
npm run tauri android dev # see scripts/dev-android.sh
```
### Container stack
Before a PR, `npm run validate` runs typecheck, extension typecheck, lint, build and tests; it is the gate CI runs in `build.yml`.
Copy `.env.example` to `.env` first. Four compose files exist:
## Configuration
The container stack is inherited from the OpenCodeUI deployment. Copy `.env.example` to `.env` first.
| File | Command | What it does |
|---|---|---|
| `docker-compose.yml` | `docker compose up -d` | Full stack: `gateway` (Caddy + Rust router, `127.0.0.1:6658` and `6659`), `frontend` (Caddy, 3000) and `backend` (`opencode serve`, 4096, 4G memory limit). |
| `docker-compose.yml` | `docker compose up -d` | Full stack: `gateway` (Caddy + Rust router, `127.0.0.1:6658` and `6659`), `frontend`, `backend` (`opencode serve`, 4096, 4G memory limit). |
| `docker-compose.standalone.yml` | `docker compose -f docker-compose.standalone.yml up -d` | Front end only, for an existing `opencode serve`. Uses `BACKEND_URL` (default `host.docker.internal:4096`) and `PORT` (default `3000`). |
| `docker-compose.host.yml` | `docker compose -f docker-compose.yml -f docker-compose.host.yml up -d` | Optional override: `backend` runs privileged with the Docker socket and the host `/` mounted at `/host`. Use only when really needed. |
| `docker-compose.host.yml` | `docker compose -f docker-compose.yml -f docker-compose.host.yml up -d` | Optional override: `backend` runs privileged with the Docker socket and host `/` mounted at `/host`. |
| `docker-compose.build.yml` | `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` | Optional override: builds gateway, frontend and backend locally from `docker/`. |
The `backend` and `gateway` images come from `ghcr.io/evandrodevbr/opencodeui-{backend,gateway}`. The `frontend` image still points at upstream `ghcr.io/lehhair/opencodeui-frontend`, because `docker-frontend.yml` has failed since 2026-06-01 and no `ghcr.io/evandrodevbr/opencodeui-frontend` was published.
### Environment variables
All variables come from `.env.example` and apply to the container stack only (the Pi extension flow needs none).
<details>
<summary>Environment variables (container stack only)</summary>
| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY` | At least one | LLM provider keys passed to the backend container. |
| `GATEWAY_PORT` | No (`6658`) | Host port of the unified entry point. |
| `PREVIEW_PORT` | No (`6659`) | Host port of the dedicated preview entry point. |
| `PREVIEW_DOMAIN` | No | Separate domain for previews, to avoid front-end asset path problems; the reverse proxy forwards it to `PREVIEW_PORT`. |
| `PREVIEW_PORT` | No (`6659`) | Host port of the preview entry point. |
| `PREVIEW_DOMAIN` | No | Separate domain for previews; the reverse proxy forwards it to `PREVIEW_PORT`. |
| `WORKSPACE` | No (`./workspace`) | Host directory mounted at `/workspace` in the backend. |
| `OPENCODE_SERVER_PASSWORD` | Public deployments | Password for the backend and the router. Set it when exposing the stack. |
| `OPENCODE_SERVER_PASSWORD` | Public deployments | Password for the backend and the router. |
| `OPENCODE_SERVER_USERNAME` | No (`opencode`) | Username paired with the password above. |
| `PUBLIC_BASE_URL` | No | Public base URL used by the router built into the gateway. |
| `ROUTER_SCAN_INTERVAL` | No (`5`) | Router scan interval. |
| `ROUTER_TOKEN_LENGTH` | No (`12`) | Length of the generated route tokens. |
| `ROUTER_PORT_RANGE` | No (`3000-9999`) | Port range the router handles. |
| `ROUTER_EXCLUDE_PORTS` | No (`4096`) | Ports the router skips. |
| `DOCKER_API_VERSION` | No (`1.40`) | Docker API version for the backend; set in `docker-compose.yml`, not in `.env.example`. |
| `USE_CHINA_MIRROR` | No (`1`) | Backend image build option: use the mirror sources below. |
| `APT_MIRROR`, `APT_SECURITY_MIRROR` | No | Debian mirrors for the backend image build. |
| `NPM_CONFIG_REGISTRY`, `NODEJS_ORG_MIRROR`, `PIP_INDEX_URL`, `PIP_TRUSTED_HOST` | No | npm, Node.js and pip sources for the backend toolchain. |
| `APT_MIRROR`, `APT_SECURITY_MIRROR`, `NPM_CONFIG_REGISTRY`, `NODEJS_ORG_MIRROR`, `PIP_INDEX_URL`, `PIP_TRUSTED_HOST` | No | Mirrors for the backend toolchain. |
| `MISE_INSTALL_URL`, `OPENCODE_INSTALL_URL` | No | Installer URLs used when building the backend image. |
## 🧱 Architecture
</details>
```mermaid
flowchart LR
UI["React UI in browser or Tauri webview"] -->|"HTTP api, SSE, WebSocket"| SRV["Pi extension server"]
PI["Pi Agent runtime"] -->|"loads extension"| SRV
SRV -->|"writes port and token"| DISC["~/.pi/agent/piagentui-port.json"]
TAURI["Tauri shell"] -->|"get_pi_agent_connection"| DISC
TAURI --> UI
```
## Project status
- The extension (`extensions/piagentui-server.ts`, Node `http` + `ws`) serves the built UI from `dist/` and injects `window.PI_BOOT_DATA {baseUrl, token}`.
- On session start it listens on port `58785` (or the next free one) and publishes the port and a random token in the discovery file.
- `GET /global/health` is open; other `/api/*` routes require `Authorization: Bearer <token>`. Access is loopback-only by default, with a LAN toggle at `/api/network/access`.
- The extension bridges sessions, models, tools, MCP, skills and commands; the full route table lives in the server file.
- The Tauri app reads the same discovery file, so the desktop build connects to the local runtime without manual setup.
- In containers, the Rust router (`src-router`, axum) sits behind Caddy as the gateway in front of the frontend and backend services.
Beta, pre-1.0 (`0.6.10`), maintained by one developer. Releases are built by `release.yml` on `v*` tags (Windows, macOS, Linux and Android artifacts); `deploy.yml` publishes the web build with `VITE_BASE_PATH=/PiAgentUI/`.
## 🗂️ Structure
```text
extensions/ Pi extension: HTTP/WebSocket server, settings, git and extension managers (Vitest)
src/ React 19 front end: api, components, features, hooks, locales, store
src-router/ Rust gateway router (axum) behind Caddy
src-tauri/ Tauri 2 desktop and mobile shell, Android project in gen/
docker/ Dockerfiles, Caddyfiles, entrypoints
scripts/ icon copy, version bump, release preparation, Android dev helper
docs/ design specs and plans (docs/superpowers/)
assets/ app icon sources
.github/ 6 workflows: build, deploy, release, docker-backend/frontend/gateway
```
## 🧪 Scripts
| Command | What it does |
|---|---|
| `npm run dev` | Vite dev server (front end only). |
| `npm run build` | `tsc -b && vite build`, output in `dist/`. |
| `npm run preview` | Serves `dist/` locally for a final check. |
| `npm run typecheck` | `tsc -b` (app and extension projects). |
| `npm run type-check` | Alias of `typecheck`. |
| `npm run typecheck:extensions` | `tsc -p tsconfig.extension.json --noEmit`. |
| `npm run lint` | `eslint .` |
| `npm run format` | `prettier . --write` |
| `npm run format:check` | `prettier . --check` |
| `npm run test` | `vitest` in watch mode. |
| `npm run test:run` | `vitest run` (needs `dist/`, so build first). |
| `npm run validate` | typecheck, extension typecheck, lint, build, tests. The gate CI runs in `build.yml`. |
| `npm run check` | format check, lint, build, tests. |
| `npm run tauri` | Tauri CLI (`dev`, `build`, `android dev`). |
| `npm run icons:tauri` | Regenerates `src-tauri/icons` from `src-tauri/app-icon.manifest.json`. |
| `npm run release:prepare` | Runs `scripts/prepare-release.mjs`. |
| `npm run postinstall` | Runs `scripts/copy-material-icons.mjs` (automatic after `npm ci`). |
Deploy notes: `dist/` is a plain SPA; under a subpath build with `VITE_BASE_PATH=/subpath/ npm run build`. `deploy.yml` publishes to GitHub Pages with `VITE_BASE_PATH=/PiAgentUI/` on pushes to `main`, and `release.yml` attaches Windows, macOS, Linux and Android artifacts on `v*` tags.
## 📚 Documentation
| Document | Content |
|---|---|
| [`docs/superpowers/specs/`](docs/superpowers/specs/) | Design specs: Pi extension migration, sessions, STT and Git controls. |
| [`docs/superpowers/plans/`](docs/superpowers/plans/) | Implementation plans and the context, skills and MCP roadmap. |
| [`CHANGELOG.md`](CHANGELOG.md) | Release history used by the release workflow. |
| [`docker/`](docker/) | Dockerfiles, Caddy configs and entrypoints. |
## 🛣️ Limitations and next steps
- Active single-developer project, pre-1.0 (`0.6.10`); some areas are still moving.
- OpenCodeUI naming is only partly cleaned: the Rust crate is `opencodeui-router`, images are `opencodeui-*`, `.env.example` comments are in Chinese, and the Docker backend runs `opencode serve`, which belongs to the inherited deployment, not the Pi extension flow.
- `docker-frontend.yml` must be fixed before `ghcr.io/evandrodevbr/opencodeui-frontend` exists; compose files pull that image from upstream until then.
- No tests for the Tauri shell or the Rust gateway beyond compilation; desktop and Android bundles are only built by the release workflow.
- Tests are component- and server-level: no end-to-end browser test and no coverage threshold. `npm run format:check` reported unformatted files at the last audit, so `npm run check` can fail on that step while `npm run validate` passes.
- `@mariozechner/pi-coding-agent` is a devDependency for types only, and npm marks that package line as deprecated in favour of `@earendil-works/pi-coding-agent`.
- One runtime per window (discovery file or manually configured server); no multi-runtime aggregation.
- OpenCodeUI naming is only partly cleaned: the Rust router crate is `opencodeui-router`, images are `opencodeui-*`, Android APKs are named `OpenCodeUI-*`, `.env.example` comments are in Chinese, and the Docker backend runs `opencode serve`, which belongs to the inherited deployment, not to the Pi extension flow.
- `docker-compose.yml` and `docker-compose.standalone.yml` still pull the upstream `ghcr.io/lehhair/opencodeui-frontend` image.
- Tests are component- and server-level (Vitest). There are no tests for the Tauri shell or the Rust router beyond compilation, no end-to-end browser test and no coverage threshold.
- Voice input needs an OpenAI-compatible STT endpoint and has no automated browser test.
- No published npm package and no hosted web demo.
## 🤝 Contributing
Issues and pull requests go to the [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues); run `npm run validate` before a PR.
Open an issue or a PR on the [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues). Before a PR, this must pass:
## License
```bash
npm run validate
```
GPL-3.0-only, see [`LICENSE`](LICENSE). PiAgentUI is a fork and rework of OpenCodeUI; the original author is credited in `src-tauri/Cargo.toml`.
## 📄 License
---
GPL-3.0-only, see [`LICENSE`](LICENSE). PiAgentUI is a fork and rework of OpenCodeUI; the original authors are credited in `src-tauri/Cargo.toml`.
<div align="center">
<sub>Made by <a href="https://evandro.dev.br">Evandro Fonseca Junior</a> · <a href="https://git.evandro.dev.br/evandro">git.evandro.dev.br</a></sub>
</div>