docs: rewrite the READMEs against verified behavior
- README.md rewritten from the real code: quick start, container stack with the actual image namespaces, Pages deploy, verification with the commands that ran, honest limitations - README.pt-BR.md rewritten; the es/ja translations get a warning pointing at the canonical README
This commit is contained in:
Evandro Fonseca Junior committed
1 parent
0e46e5857e
commit
039d25f084
4 files changed
+310
-342
No files matched your search
@@ -6,6 +6,8 @@
|
||||
|
||||
[English (US)](./README.md) | [Português (BR)](./README.pt-BR.md) | **Español** | [日本語](./README.ja.md)
|
||||
|
||||
> Esta traducción puede quedar por detrás de la versión de referencia, que es el [README principal](./README.md). Repositorio: https://github.com/evandrodevbr/PiAgentUI
|
||||
|
||||
PiAgentUI es una interfaz moderna web y de escritorio para **Pi Agent**. No es solo una capa visual de chat: el objetivo es convertirse en una aplicación completa de agentes, en la misma categoría de producto que Codex, Claude Desktop y otros entornos de desarrollo agent-first.
|
||||
|
||||
PiAgentUI trata el runtime real de Pi como la fuente de verdad. Sesiones, metadatos de modelos, uso de contexto, tool calls, skills, configuración MCP y slash commands vienen de Pi siempre que sea posible, en lugar de recrearse como estado falso de interfaz.
|
||||
|
||||
@@ -6,6 +6,8 @@
|
||||
|
||||
[English (US)](./README.md) | [Português (BR)](./README.pt-BR.md) | [Español](./README.es.md) | **日本語**
|
||||
|
||||
> この翻訳は基準となる [メイン README](./README.md) より古い可能性があります。リポジトリ: https://github.com/evandrodevbr/PiAgentUI
|
||||
|
||||
PiAgentUI は **Pi Agent** のためのモダンな Web / デスクトップ UI です。単なるチャット画面ではありません。最終的には Codex や Claude Desktop のような、エージェント中心の本格的な開発アプリになることを目指しています。
|
||||
|
||||
PiAgentUI は、実際の Pi runtime を信頼できる唯一の情報源として扱います。セッション、モデルメタデータ、コンテキスト使用量、tool call、skills、MCP 設定、slash command は、可能な限り Pi から取得し、UI 側だけの仮の状態として再実装しません。
|
||||
|
||||
@@ -1,241 +1,207 @@
|
||||
<p align="center">
|
||||
<img src="./src/assets/images/logo/PiAgentUiBlack%20%283%29.png" alt="PiAgentUI logo" width="760" />
|
||||
</p>
|
||||
# PiAgentUI
|
||||
|
||||
<h1 align="center">PiAgentUI</h1>
|
||||
<p align="center">
|
||||
<strong>Professional Desktop & Web UI for AI Coding Agents</strong><br/>
|
||||
<em>Pi Agent · Claude Code · Codex · OpenCode · Cursor · Copilot</em>
|
||||
</p>
|
||||
**Desktop and web workspace for AI coding agents: real Pi Agent sessions, streaming chat, MCP and skills panels, terminal, file explorer and a Tauri desktop app.**
|
||||
|
||||
<p align="center">
|
||||
<img src="https://img.shields.io/badge/version-0.6.10-blue" alt="Version" />
|
||||
<img src="https://img.shields.io/badge/license-GPL--3.0-green" alt="License" />
|
||||
<img src="https://img.shields.io/badge/platform-Tauri%202%20%7C%20Web-brightgreen" alt="Platform" />
|
||||
<img src="https://img.shields.io/badge/framework-React%2019%20%7C%20TypeScript-61DAFB" alt="Framework" />
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://github.com/evandrodevbr/PiAgentUI/actions/workflows/build.yml)
|
||||
|
||||
**English (US)** | [Português (BR)](./README.pt-BR.md) | [Español](./README.es.md) | [日本語](./README.ja.md)
|
||||
|
||||
## TL;DR
|
||||
## About
|
||||
|
||||
PiAgentUI is a **full-featured workspace for AI coding agents** — sessions, model switching, MCP tools, skills browser, voice input, terminal, file explorer, and Tauri desktop app. Built for Pi Agent but compatible with Claude Code, Codex, OpenCode, Cursor, and any agent that speaks SSE/HTTP.
|
||||
PiAgentUI is a chat and workspace front end for the Pi Agent runtime. Instead of a bare terminal, it gives you sessions, model switching, tool calls rendered as cards, MCP server metadata, skills grouped by source, slash commands, Git controls, a terminal, and a file explorer in one window, as a web app or as a Tauri desktop app.
|
||||
|
||||
> **Category:** AI Agent UI · Agent Desktop Client · MCP GUI · Coding Copilot Interface
|
||||
> **Status:** Active development — production-grade chat, evolving fast. Expect weekly releases.
|
||||
The project is Pi-first: sessions, models, context usage, tool calls, skills, MCP configuration and slash commands come from the Pi runtime whenever possible. The UI caches and enriches that data for presentation but does not invent agent state. It is a rename and rework of the OpenCodeUI base, and part of that inheritance is still visible (see [Current state and limitations](#current-state-and-limitations)).
|
||||
|
||||
## Software preview
|
||||
|
||||
These screenshots show the current PiAgentUI experience: a dark, focused agent workspace with real Pi sessions, model selection, MCP metadata, settings, tool-aware chat, and side panels.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
# Clone and install
|
||||
git clone https://github.com/lehhair/OpenCodeUI.git
|
||||
cd OpenCodeUI
|
||||
npm install
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
|
||||
# Or build desktop app
|
||||
npm run tauri dev
|
||||
```
|
||||
|
||||
Requires **Node.js ≥ 22** and **Pi Agent** installed. The UI auto-discovers the Pi runtime via `~/.pi/agent/piagentui-port.json`.
|
||||
|
||||
## What PiAgentUI does today
|
||||
|
||||
- **Agent chat with streaming** — live assistant output through SSE, stable message reconciliation, markdown rendering, code highlighting, reasoning parts, and tool cards.
|
||||
- **Real Pi sessions** — session list, active-session routing, restart-safe history loading, derived session titles, and selected-session send routing.
|
||||
- **Tool output as tool cards** — tool calls/results stay attached to assistant messages instead of leaking as normal chat text.
|
||||
- **Runtime context usage** — context usage comes from Pi runtime when available; unknown/compacted context is shown safely instead of `NaN`.
|
||||
- **Model metadata** — Pi provider/model identity remains authoritative, with optional OpenRouter catalog metadata used only for extra details like context, output, modality, pricing, and tokenizer hints.
|
||||
- **Skills panel** — real skills are parsed from the effective Pi prompt and grouped by source: global, project, package, and other.
|
||||
- **MCP metadata panel** — reads configured MCP servers from local/global config files and surfaces transport, command, URL, lifecycle, direct tools, and source.
|
||||
- **Pi slash commands** — `/api/commands/list` exposes Pi built-in commands plus dynamic extension, prompt, and skill commands.
|
||||
- **Attachments and multimodal input** — file/image/PDF/audio/video attachment affordances follow the selected model capabilities.
|
||||
- **Terminal and file tooling** — integrated terminal, file explorer, syntax highlighting, diff-oriented components, and Tauri desktop integration.
|
||||
- **Keyboard-first UI** — command palette, configurable keybindings, split panes, model selector, project/session navigation, and responsive layouts.
|
||||
|
||||
## Product direction
|
||||
|
||||
PiAgentUI is moving toward a complete agent app:
|
||||
|
||||
1. **Visual actions for every Pi command** — slash commands remain available, but frequent actions should become buttons, menus, dialogs, or panels.
|
||||
2. **Voice input and realtime transcription** — microphone recording, partial transcript deltas, final transcript insertion into the composer, and OpenAI-compatible STT provider configuration.
|
||||
3. **Deeper MCP integration** — beyond metadata: connect, authenticate, inspect tools, and execute MCP workflows from the UI.
|
||||
4. **Full session control** — fork, clone, tree navigation, import/export/share, branch summaries, and context management as first-class UI flows.
|
||||
5. **Desktop-grade experience** — a polished Tauri app with local runtime discovery, secure settings, notifications, and richer workspace controls.
|
||||
|
||||
## Audio and transcription roadmap
|
||||
|
||||
PiAgentUI already supports attaching audio files when the selected model declares audio input support. The planned voice system adds live speech-to-text directly in the composer.
|
||||
|
||||
Recommended architecture:
|
||||
|
||||
- **Default realtime provider:** OpenAI Realtime Transcription with `gpt-realtime-whisper` for low-latency partial transcripts.
|
||||
- **Default file fallback:** OpenAI Audio Transcriptions with `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, or `whisper-1`.
|
||||
- **Custom providers:** user-configurable OpenAI-compatible STT APIs, such as providers that implement `POST /v1/audio/transcriptions`.
|
||||
|
||||
Planned UX:
|
||||
|
||||
- microphone button in the composer;
|
||||
- recording and permission states;
|
||||
- partial transcript overlay;
|
||||
- final transcript inserted into the input;
|
||||
- optional append/replace behavior;
|
||||
- auto-send disabled by default;
|
||||
- recoverable error handling for permissions, network failures, and provider errors.
|
||||
|
||||
Planned provider config shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "openai-compatible",
|
||||
"mode": "file",
|
||||
"baseUrl": "https://api.example.com/v1",
|
||||
"transcriptionEndpoint": "/audio/transcriptions",
|
||||
"transcriptionModel": "openai/whisper-large-v3",
|
||||
"language": "en"
|
||||
}
|
||||
```
|
||||
|
||||
Realtime support is treated as a separate capability because OpenAI-compatible HTTP transcription does not guarantee WebSocket compatibility.
|
||||
|
||||
## Architecture
|
||||
## How it works
|
||||
|
||||
```text
|
||||
PiAgentUI
|
||||
├─ React/Vite frontend
|
||||
│ ├─ chat, message rendering, input, panels, settings
|
||||
│ ├─ local stores for UI preferences
|
||||
│ └─ SSE/API clients for PiAgentUI local endpoints
|
||||
├─ Pi extension backend
|
||||
│ └─ extensions/piagentui-server.ts
|
||||
│ ├─ exposes local /api/* endpoints
|
||||
│ ├─ bridges to Pi runtime/session/model APIs
|
||||
│ ├─ streams Pi events to the browser
|
||||
│ └─ reads local metadata such as MCP config and skills
|
||||
└─ Pi Agent runtime
|
||||
├─ sessions
|
||||
├─ models/providers
|
||||
├─ tools
|
||||
├─ skills
|
||||
├─ MCP
|
||||
└─ slash commands
|
||||
browser window / Tauri webview
|
||||
|
|
||||
| HTTP /api/* + SSE /global/event + WebSocket
|
||||
v
|
||||
Pi extension server (extensions/piagentui-server.ts, Node http + ws)
|
||||
|-- serves the built UI from dist/ and injects window.PI_BOOT_DATA {baseUrl, token}
|
||||
|-- writes connection info to ~/.pi/agent/piagentui-port.json {port, token}
|
||||
|-- enforces bearer-token auth on /api/* and loopback-only access by default
|
||||
|-- bridges sessions, models, tools, MCP, skills and commands
|
||||
^
|
||||
| loaded by the runtime
|
||||
Pi Agent process
|
||||
```
|
||||
|
||||
The UI should not invent runtime state when Pi already knows the answer. PiAgentUI can cache and enrich data for UX, but Pi remains authoritative for agent behavior.
|
||||
- On session start the extension listens on port `58785` (or the next free port) and publishes the selected port plus a random token in the discovery file.
|
||||
- `GET /global/health` is open; every other `/api/*` route requires `Authorization: Bearer <token>`.
|
||||
- The Tauri app reads the same discovery file through the `get_pi_agent_connection` Rust command, so the desktop build connects to the local runtime without manual configuration.
|
||||
- `npm run dev` (Vite) is a front-end-only development server; it proxies `/api` to `127.0.0.1:4096` with the `/api` prefix stripped, so point it at a compatible server or use the extension-served build for the Pi flow.
|
||||
|
||||
## Tech stack
|
||||
## Stack
|
||||
|
||||
| Area | Stack |
|
||||
| ------------------- | --------------------------------------------- |
|
||||
| UI | React 19, TypeScript |
|
||||
| Build | Vite 8 |
|
||||
| Styling | Tailwind CSS v4 plus project design tokens |
|
||||
| Desktop | Tauri 2 |
|
||||
| Markdown | Streamdown / markdown rendering pipeline |
|
||||
| Syntax highlighting | Shiki |
|
||||
| Terminal | xterm.js |
|
||||
| Testing | Vitest, Testing Library |
|
||||
| Local backend | Pi extension, Node HTTP server, WebSocket/SSE |
|
||||
| Area | Choice |
|
||||
|---|---|
|
||||
| UI | React 19, TypeScript 5.9 |
|
||||
| Build | Vite 8 (rolldown), `tsc -b` as the type gate |
|
||||
| Styling | Tailwind CSS 4 plus project design tokens |
|
||||
| Desktop / mobile | Tauri 2 (Rust 1.85+), Android targets generated in `src-tauri/gen` |
|
||||
| Markdown and code | Streamdown, Shiki, KaTeX |
|
||||
| Terminal | xterm.js |
|
||||
| i18n | i18next, locales `en`, `pt-BR`, `es`, `ja`, `zh-CN`, `hi`, `bn`, `ar` |
|
||||
| Tests | Vitest 4, Testing Library, jsdom |
|
||||
| Local backend | Pi extension: Node HTTP server plus `ws` (SSE and WebSocket) |
|
||||
| Gateway (containers) | Rust router (`src-router`, axum) in front of Caddy |
|
||||
| Packages | npm with `package-lock.json` |
|
||||
|
||||
## Local development
|
||||
## Requirements
|
||||
|
||||
Install dependencies:
|
||||
- Node.js `>=22` (CI runs Node 22; verified locally on Node 24.20.0)
|
||||
- npm `>=10` (the repository is npm-based; `package-lock.json` is authoritative)
|
||||
- Rust `1.85+` only if you build the desktop app or the gateway
|
||||
- Docker only for the container stack in `docker/`
|
||||
- Pi Agent installed locally to have real sessions and models; without it the UI starts in standalone mode and only shows the server connection dialog
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
npm install
|
||||
git clone https://github.com/evandrodevbr/PiAgentUI.git
|
||||
cd PiAgentUI
|
||||
npm ci # 615 packages, runs scripts/copy-material-icons.mjs
|
||||
npm run build # tsc -b && vite build -> dist/
|
||||
npm run dev # Vite dev server on http://localhost:5173
|
||||
```
|
||||
|
||||
Start the frontend dev server:
|
||||
Web UI served by the Pi extension (this is the path that talks to a real Pi runtime):
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
npm run build # the extension serves dist/
|
||||
# with Pi Agent running this repository as a Pi package (see package.json -> "pi")
|
||||
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
|
||||
# open http://127.0.0.1:58785
|
||||
```
|
||||
|
||||
Build the app:
|
||||
Desktop app:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run tauri dev # development window, uses the Vite dev server
|
||||
npm run tauri build # bundles per src-tauri/tauri.conf.json (deb on Linux, dmg, nsis)
|
||||
```
|
||||
|
||||
Run tests:
|
||||
Android (see `scripts/dev-android.sh` and the Android job in the release workflow):
|
||||
|
||||
```bash
|
||||
npm run test:run
|
||||
npm run tauri android dev
|
||||
```
|
||||
|
||||
Run type checks:
|
||||
## Usage
|
||||
|
||||
Local endpoints exposed by the extension server. All of them, except `/global/health` and the SSE route, require the bearer token from the discovery file.
|
||||
|
||||
| Endpoint | Purpose |
|
||||
|---|---|
|
||||
| `GET /global/health` | Liveness probe, returns `{"status":"ok","pi":"ready"}` |
|
||||
| `GET /global/event` | SSE event stream (sessions, message parts, status) |
|
||||
| `GET /api/models` | Model list with normalized capabilities |
|
||||
| `GET /api/sessions` | Session list |
|
||||
| `POST /api/sessions` | Create a session |
|
||||
| `POST /api/sessions/abort` | Abort the running turn |
|
||||
| `GET /api/sessions/:id/messages` | Session history normalized for rendering |
|
||||
| `GET /api/sessions/:id/context` | Context usage of the active session |
|
||||
| `POST /api/messages/send` | Send a user message to a session |
|
||||
| `GET /api/skills` | Effective skills grouped by source |
|
||||
| `GET /api/mcp/status` | Configured MCP servers (transport, command, URL, source) |
|
||||
| `GET /api/commands/list` | Built-in and dynamic slash commands |
|
||||
| `GET /api/agents`, `GET /api/files/list`, `GET /api/permissions/list`, `GET /api/questions/list` | Runtime inventory for the panels |
|
||||
| `GET /api/vcs/status`, `/info`, `/branches` | Git state used by the composer controls |
|
||||
| `GET /api/extensions/list` | Extension catalog for the extensions panel |
|
||||
| `GET /api/settings/stt`, `/api/settings/tts` | Voice settings (STT/TTS) |
|
||||
| `GET /api/network/access`, `POST /api/network/access` | LAN access toggle (loopback-only by default) |
|
||||
|
||||
The full route table, including Git and extension mutations, lives in [`extensions/piagentui-server.ts`](extensions/piagentui-server.ts). Ports and paths can change; the discovery file is the source of truth for the port and token.
|
||||
|
||||
Auditing the agent from a shell works too, for example:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run typecheck:extensions
|
||||
TOKEN=$(node -e "console.log(require(process.env.HOME+'/.pi/agent/piagentui-port.json').token)")
|
||||
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:58785/api/models | head -c 300
|
||||
```
|
||||
|
||||
Full validation:
|
||||
## Production and deploy
|
||||
|
||||
```bash
|
||||
npm run validate
|
||||
npm run build # tsc -b && vite build; output in dist/ (about 14 MB, static)
|
||||
npm run preview # serves dist/ locally for a final check
|
||||
```
|
||||
|
||||
## Pi extension runtime
|
||||
- Static hosting: `dist/` is a plain SPA. If it is mounted under a subpath, build with `VITE_BASE_PATH=/subpath/ npm run build`.
|
||||
- Container (front end plus Caddy): `docker/Dockerfile.frontend` builds the UI on Node 22 and serves it from Caddy on port 3000.
|
||||
- Full container stack: `docker-compose.yml` runs `gateway` (Caddy plus the Rust router on 6658/6659), `frontend` and `backend`. Copy `.env.example` to `.env` first. Images: `backend` and `gateway` come from `ghcr.io/evandrodevbr/opencodeui-{backend,gateway}` (published by the `docker-backend.yml` and `docker-gateway.yml` workflows); the `frontend` image still points at the upstream `ghcr.io/lehhair/opencodeui-frontend` because `docker-frontend.yml` has been failing since 2026-06-01 and no `ghcr.io/evandrodevbr/opencodeui-frontend` was ever published. To build all three locally use `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`.
|
||||
- GitHub Pages: `.github/workflows/deploy.yml` builds `dist/` with `VITE_BASE_PATH=/PiAgentUI/` and publishes it on every push to `main` (enable Pages with source "GitHub Actions" the first time).
|
||||
- Desktop and mobile releases: `.github/workflows/release.yml` runs on `v*` tags and attaches Windows, macOS, Linux and Android artifacts to the GitHub release.
|
||||
|
||||
PiAgentUI is registered as a Pi extension in `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"extensions": ["./extensions/piagentui-server.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When the extension starts, it writes local discovery metadata to:
|
||||
## Project structure
|
||||
|
||||
```text
|
||||
~/.pi/agent/piagentui-port.json
|
||||
extensions/ Pi extension: HTTP/WebSocket server, settings store, git and
|
||||
extension managers, all with Vitest tests
|
||||
src/ React front end (Vite entry in index.html)
|
||||
├── api/ HTTP/SSE clients and the request pipeline
|
||||
├── components/ shared UI pieces (code blocks, diffs, command palette)
|
||||
├── features/ chat, input, messages, tools, sessions, settings, slash commands
|
||||
├── hooks/ session, events, transcription, permissions
|
||||
├── locales/ 8 translated bundles
|
||||
├── store/ Zustand-style stores (sessions, messages, layout, theme)
|
||||
└── constants/ API base URL, storage keys, UI metrics
|
||||
src-router/ Rust gateway router (axum) behind Caddy
|
||||
src-tauri/ Tauri 2 desktop and mobile shell (Rust), Android project in gen/
|
||||
docker/ Dockerfiles, Caddy configs, entrypoints
|
||||
scripts/ icon copy, version bump, release preparation, Android dev helper
|
||||
docs/superpowers/ design specs and plans written during the migration
|
||||
```
|
||||
|
||||
The web app uses that local port/token information to talk to the running extension server. Some backend changes require restarting or reloading the Pi extension process before the browser sees the new behavior.
|
||||
## Verification
|
||||
|
||||
## Important local endpoints
|
||||
Everything below was executed on a clean clone in this repository state:
|
||||
|
||||
| Endpoint | Purpose |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `GET /api/models` | Real Pi model list plus normalized capability metadata |
|
||||
| `GET /api/sessions` | Session list parsed from Pi session files |
|
||||
| `GET /api/sessions/:id/messages` | Session history normalized for UI rendering |
|
||||
| `GET /api/sessions/:id/context` | Runtime context usage for the active session |
|
||||
| `POST /api/messages/send` | Send user message to the requested Pi session |
|
||||
| `GET /api/skills` | Effective Pi skills grouped by source |
|
||||
| `GET /api/mcp/status` | Configured MCP server metadata |
|
||||
| `GET /api/commands/list` | Built-in and dynamic Pi slash commands |
|
||||
| `GET /global/event` | SSE event stream from PiAgentUI backend |
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `npm ci` | 615 packages installed, postinstall copies 266 material icons |
|
||||
| `npm run typecheck` | exit 0 (`tsc -b`, app + extension projects) |
|
||||
| `npm run typecheck:extensions` | exit 0 |
|
||||
| `npm run lint` | exit 0 (0 errors, 109 warnings) |
|
||||
| `npm run build` | exit 0, `dist/` about 14 MB |
|
||||
| `npm run test:run` | 89 files, 319 tests, all passing |
|
||||
| `npm run validate` | exit 0 (the same gate CI runs in `build.yml`) |
|
||||
| `cargo check` in `src-router/` | exit 0 |
|
||||
| `cargo check --manifest-path src-tauri/Cargo.toml` | exit 0 (1 warning) |
|
||||
| extension server over HTTP | `/global/health` 200, `/` 200 with `PI_BOOT_DATA`, `/api/models` 200 with token and 401 without, `/api/sessions`, `/api/sessions/:id/messages`, `/api/sessions/:id/context`, `/api/skills`, `/api/mcp/status`, `/api/commands/list`, `/api/network/access` all 200, `/global/event` 200 `text/event-stream` |
|
||||
|
||||
## Development principles
|
||||
Two things to know when running the suite: `npm run test:run` needs `dist/` to exist, because the extension server test fetches the served `index.html`, so `npm run build` must run first (that is the order in `npm run validate`); and `npm run format:check` currently reports 67 files that are not Prettier-formatted, so `npm run check` fails on that step even though the CI gate passes.
|
||||
|
||||
- Prefer real Pi runtime data over mocked UI-only state.
|
||||
- Keep OpenRouter metadata as catalog enrichment only; never replace Pi provider/model identity with it.
|
||||
- Treat unknown runtime values explicitly instead of rendering misleading numbers.
|
||||
- Add tests before behavior changes whenever possible.
|
||||
- Keep tool results inside tool cards.
|
||||
- Keep UI work aligned with the existing theme, motion, spacing, and panel patterns.
|
||||
- Document what is implemented separately from what is planned.
|
||||
## Current state and limitations
|
||||
|
||||
## Repository notes
|
||||
- Active single-developer project, pre-1.0 (`0.6.10`). The chat, sessions, MCP, skills and command panels work against a real Pi runtime; some areas are still moving.
|
||||
- Naming inheritance from the OpenCodeUI base is only partially cleaned: the Rust crate is `opencodeui-router`, container images are `opencodeui-*`, `.env.example` comments are in Chinese, and the Docker stack runs an `opencode serve` backend that belongs to the inherited deployment, not to the Pi extension flow.
|
||||
- There is no test for the Tauri shell or the Rust gateway beyond compilation; the Android and desktop bundles are only built by the release workflow.
|
||||
- The suite is component- and server-level; there is no end-to-end browser test and no coverage threshold.
|
||||
- `@mariozechner/pi-coding-agent` is a devDependency for types only (the runtime provides the real extension API), and npm marks that package line as deprecated in favour of `@earendil-works/pi-coding-agent`.
|
||||
- The front end talks to one runtime per window: the discovery file or a manually configured server. There is no multi-runtime aggregation.
|
||||
- Voice input exists in the UI (`src/hooks/useVoiceTranscription.ts`) and requires an OpenAI-compatible STT endpoint configured in settings; it is not covered by an automated browser test.
|
||||
- No published npm package and no hosted web demo; both README and code assume a local runtime.
|
||||
- `docker-frontend.yml` last ran on 2026-06-01 and failed at the build step, so `ghcr.io/evandrodevbr/opencodeui-frontend` was never published (verified against GHCR with the owner credentials); the compose files pull that one image from upstream until the workflow is fixed.
|
||||
|
||||
This project still contains inherited naming from the original OpenCodeUI base in a few places, including package metadata and older documentation files. The current direction is PiAgentUI-first, and future cleanup should migrate remaining OpenCodeUI naming without breaking local workflows.
|
||||
## Documentation
|
||||
|
||||
| Document | Content |
|
||||
|---|---|
|
||||
| [`docs/superpowers/specs/`](docs/superpowers/specs/) | Design specs for the Pi extension migration, sessions, STT and Git controls |
|
||||
| [`docs/superpowers/plans/`](docs/superpowers/plans/) | Implementation plans and the roadmap for context, skills and MCP |
|
||||
| [`CHANGELOG.md`](CHANGELOG.md) | Release history used by the release workflow |
|
||||
| [`docker/`](docker/) | Dockerfiles, Caddy configs and entrypoints for the container stack |
|
||||
|
||||
## License
|
||||
|
||||
This repository currently follows the license declared in `package.json`: `GPL-3.0-only`.
|
||||
GPL-3.0-only, as declared in `package.json` and [`LICENSE`](LICENSE). PiAgentUI is a fork and rework of OpenCodeUI; the original authors are credited in `src-tauri/Cargo.toml`.
|
||||
+153
-155
@@ -4,209 +4,207 @@
|
||||
|
||||
# PiAgentUI
|
||||
|
||||
**Workspace desktop e web para agentes de código: sessões reais do Pi Agent, chat com streaming, painéis de MCP e skills, terminal, explorador de arquivos e app desktop em Tauri.**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://github.com/evandrodevbr/PiAgentUI/actions/workflows/build.yml)
|
||||
|
||||
[English (US)](./README.md) | **Português (BR)** | [Español](./README.es.md) | [日本語](./README.ja.md)
|
||||
|
||||
PiAgentUI é uma interface moderna web e desktop para o **Pi Agent**. Ele não é apenas uma camada visual de chat: o objetivo é evoluir para um aplicativo completo de agentes, na mesma categoria de produto de Codex, Claude Desktop e outros ambientes agent-first para desenvolvimento.
|
||||
## Sobre
|
||||
|
||||
O PiAgentUI trata o runtime real do Pi como fonte de verdade. Sessões, metadados de modelo, uso de contexto, tool calls, skills, configuração MCP e slash commands vêm do Pi sempre que possível, em vez de serem recriados como estado falso de interface.
|
||||
PiAgentUI é uma interface de chat e um workspace para o runtime do Pi Agent. No lugar de um terminal cru, ele reúne sessões, troca de modelo, tool calls em cards, metadados de servidores MCP, skills agrupadas por origem, slash commands, controles de Git, terminal e explorador de arquivos, como aplicação web ou como app desktop Tauri.
|
||||
|
||||
> **Status do projeto:** desenvolvimento local ativo. Algumas áreas já estão próximas de produto, enquanto outras ainda mudam rapidamente.
|
||||
O projeto é Pi-first: sessões, modelos, uso de contexto, tool calls, skills, configuração MCP e slash commands vêm do runtime do Pi sempre que possível. A UI cacheia e enriquece esses dados para apresentação, mas não inventa estado do agente. É um fork e uma reescrita da base OpenCodeUI, e parte dessa herança ainda aparece (veja [Estado atual e limitações](#estado-atual-e-limitações)).
|
||||
|
||||
## Demonstração do software
|
||||
|
||||
Estas capturas mostram a experiência atual do PiAgentUI: um workspace escuro e focado para agentes, com sessões reais do Pi, seleção de modelos, metadados MCP, settings, chat com ferramentas e painéis laterais.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## O que o PiAgentUI já faz hoje
|
||||
|
||||
- **Chat com streaming** — saída ao vivo via SSE, reconciliação estável de mensagens, markdown, code highlight, partes de reasoning e cards de ferramentas.
|
||||
- **Sessões reais do Pi** — lista de sessões, roteamento para sessão ativa, histórico seguro após restart, títulos derivados e envio para a sessão selecionada.
|
||||
- **Tool output em cards** — tool calls/results ficam anexados às mensagens do assistente, sem vazar como texto normal no chat.
|
||||
- **Uso real de contexto** — o uso de contexto vem do runtime do Pi quando disponível; contexto desconhecido/compactado é exibido de forma segura em vez de `NaN`.
|
||||
- **Metadados de modelos** — identidade de provider/modelo vem do Pi; o catálogo OpenRouter local é usado apenas como enriquecimento de detalhes.
|
||||
- **Painel de Skills** — skills reais são lidas do prompt efetivo do Pi e agrupadas por origem: global, project, package e other.
|
||||
- **Painel MCP** — lê servidores MCP configurados em arquivos locais/globais e mostra transporte, comando, URL, lifecycle, direct tools e origem.
|
||||
- **Slash commands do Pi** — `/api/commands/list` expõe comandos built-in do Pi e comandos dinâmicos de extensões, prompts e skills.
|
||||
- **Anexos multimodais** — suporte visual a arquivos/imagens/PDF/áudio/vídeo conforme as capacidades do modelo selecionado.
|
||||
- **Terminal e arquivos** — terminal integrado, explorador de arquivos, syntax highlighting, componentes de diff e integração desktop via Tauri.
|
||||
- **UI keyboard-first** — command palette, atalhos configuráveis, split panes, seletor de modelo, navegação por projeto/sessão e layouts responsivos.
|
||||
|
||||
## Direção do produto
|
||||
|
||||
O PiAgentUI está caminhando para virar um app completo de agentes:
|
||||
|
||||
1. **Ações visuais para todos os comandos do Pi** — slash commands continuam disponíveis, mas ações frequentes devem virar botões, menus, diálogos ou painéis.
|
||||
2. **Entrada por voz e transcrição em tempo real** — gravação de microfone, deltas parciais, inserção da transcrição final no composer e configuração de provedores STT OpenAI-compatible.
|
||||
3. **Integração MCP mais profunda** — além de metadados: conectar, autenticar, inspecionar ferramentas e executar workflows MCP pela UI.
|
||||
4. **Controle completo de sessões** — fork, clone, navegação em árvore, import/export/share, branch summaries e gerenciamento de contexto como fluxos nativos.
|
||||
5. **Experiência desktop completa** — app Tauri polido com descoberta local de runtime, settings seguros, notificações e controles ricos de workspace.
|
||||
|
||||
## Roadmap de áudio e transcrição
|
||||
|
||||
O PiAgentUI já aceita anexos de áudio quando o modelo selecionado declara suporte a áudio. O sistema planejado de voz adiciona speech-to-text ao vivo diretamente no composer.
|
||||
|
||||
Arquitetura recomendada:
|
||||
|
||||
- **Provedor realtime padrão:** OpenAI Realtime Transcription com `gpt-realtime-whisper` para transcrição parcial de baixa latência.
|
||||
- **Fallback por arquivo:** OpenAI Audio Transcriptions com `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` ou `whisper-1`.
|
||||
- **Provedores customizados:** APIs STT OpenAI-compatible configuráveis pelo usuário, como provedores que implementam `POST /v1/audio/transcriptions`.
|
||||
|
||||
UX planejada:
|
||||
|
||||
- botão de microfone no composer;
|
||||
- estados de gravação e permissão;
|
||||
- overlay de transcrição parcial;
|
||||
- texto final inserido no input;
|
||||
- comportamento configurável de append/replace;
|
||||
- auto-send desligado por padrão;
|
||||
- tratamento recuperável para erros de permissão, rede e provedor.
|
||||
|
||||
Exemplo de configuração de provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "openai-compatible",
|
||||
"mode": "file",
|
||||
"baseUrl": "https://api.example.com/v1",
|
||||
"transcriptionEndpoint": "/audio/transcriptions",
|
||||
"transcriptionModel": "openai/whisper-large-v3",
|
||||
"language": "pt"
|
||||
}
|
||||
```
|
||||
|
||||
Suporte realtime é tratado como capability separada, porque compatibilidade HTTP com a OpenAI não garante compatibilidade WebSocket.
|
||||
|
||||
## Arquitetura
|
||||
## Como funciona
|
||||
|
||||
```text
|
||||
PiAgentUI
|
||||
├─ Frontend React/Vite
|
||||
│ ├─ chat, renderização de mensagens, input, painéis e settings
|
||||
│ ├─ stores locais para preferências de UI
|
||||
│ └─ clientes SSE/API para endpoints locais do PiAgentUI
|
||||
├─ Backend como extensão Pi
|
||||
│ └─ extensions/piagentui-server.ts
|
||||
│ ├─ expõe endpoints locais /api/*
|
||||
│ ├─ faz ponte com runtime/sessões/modelos do Pi
|
||||
│ ├─ transmite eventos do Pi para o browser
|
||||
│ └─ lê metadados locais como MCP config e skills
|
||||
└─ Runtime Pi Agent
|
||||
├─ sessões
|
||||
├─ modelos/providers
|
||||
├─ ferramentas
|
||||
├─ skills
|
||||
├─ MCP
|
||||
└─ slash commands
|
||||
janela do navegador / webview Tauri
|
||||
|
|
||||
| HTTP /api/* + SSE /global/event + WebSocket
|
||||
v
|
||||
Servidor da extensão Pi (extensions/piagentui-server.ts, Node http + ws)
|
||||
|-- serve o build da UI a partir de dist/ e injeta window.PI_BOOT_DATA {baseUrl, token}
|
||||
|-- grava os dados de conexão em ~/.pi/agent/piagentui-port.json {port, token}
|
||||
|-- exige bearer token em /api/* e restringe o acesso ao loopback por padrão
|
||||
|-- faz a ponte para sessões, modelos, ferramentas, MCP, skills e comandos
|
||||
^
|
||||
| carregado pelo runtime
|
||||
Processo do Pi Agent
|
||||
```
|
||||
|
||||
A UI não deve inventar estado de runtime quando o Pi já sabe a resposta. O PiAgentUI pode cachear e enriquecer dados para UX, mas o Pi continua autoritativo para o comportamento do agente.
|
||||
- Ao iniciar uma sessão, a extensão escuta na porta `58785` (ou na próxima livre) e publica a porta escolhida e um token aleatório no arquivo de descoberta.
|
||||
- `GET /global/health` é aberto; todas as outras rotas `/api/*` exigem `Authorization: Bearer <token>`.
|
||||
- O app Tauri lê o mesmo arquivo de descoberta pelo comando Rust `get_pi_agent_connection`, então o build desktop se conecta ao runtime local sem configuração manual.
|
||||
- `npm run dev` (Vite) serve apenas o front end em desenvolvimento; ele faz proxy de `/api` para `127.0.0.1:4096` removendo o prefixo `/api`. Aponte para um servidor compatível ou use o build servido pela extensão para o fluxo Pi.
|
||||
|
||||
## Stack técnica
|
||||
## Stack
|
||||
|
||||
| Área | Stack |
|
||||
| ------------------- | -------------------------------------------- |
|
||||
| UI | React 19, TypeScript |
|
||||
| Build | Vite 8 |
|
||||
| Estilo | Tailwind CSS v4 e design tokens do projeto |
|
||||
| Desktop | Tauri 2 |
|
||||
| Markdown | Streamdown / pipeline de markdown |
|
||||
| Syntax highlighting | Shiki |
|
||||
| Terminal | xterm.js |
|
||||
| Testes | Vitest, Testing Library |
|
||||
| Backend local | Extensão Pi, Node HTTP server, WebSocket/SSE |
|
||||
| Área | Escolha |
|
||||
|---|---|
|
||||
| UI | React 19, TypeScript 5.9 |
|
||||
| Build | Vite 8 (rolldown), com `tsc -b` como gate de tipos |
|
||||
| Estilo | Tailwind CSS 4 e design tokens do projeto |
|
||||
| Desktop e mobile | Tauri 2 (Rust 1.85+), alvos Android gerados em `src-tauri/gen` |
|
||||
| Markdown e código | Streamdown, Shiki, KaTeX |
|
||||
| Terminal | xterm.js |
|
||||
| i18n | i18next, locales `en`, `pt-BR`, `es`, `ja`, `zh-CN`, `hi`, `bn`, `ar` |
|
||||
| Testes | Vitest 4, Testing Library, jsdom |
|
||||
| Backend local | Extensão Pi: servidor HTTP Node com `ws` (SSE e WebSocket) |
|
||||
| Gateway (containers) | Roteador Rust (`src-router`, axum) na frente do Caddy |
|
||||
| Pacotes | npm com `package-lock.json` |
|
||||
|
||||
## Desenvolvimento local
|
||||
## Requisitos
|
||||
|
||||
Instalar dependências:
|
||||
- Node.js `>=22` (o CI roda Node 22; verificado localmente em Node 24.20.0)
|
||||
- npm `>=10` (o repositório é npm; `package-lock.json` é a referência)
|
||||
- Rust `1.85+` apenas para buildar o app desktop ou o gateway
|
||||
- Docker apenas para a stack de containers em `docker/`
|
||||
- Pi Agent instalado para ter sessões e modelos reais; sem ele a UI sobe em modo standalone e mostra apenas o diálogo de conexão com servidores
|
||||
|
||||
## Início rápido
|
||||
|
||||
```bash
|
||||
npm install
|
||||
git clone https://github.com/evandrodevbr/PiAgentUI.git
|
||||
cd PiAgentUI
|
||||
npm ci # 615 pacotes; roda scripts/copy-material-icons.mjs
|
||||
npm run build # tsc -b && vite build -> dist/
|
||||
npm run dev # servidor de desenvolvimento Vite em http://localhost:5173
|
||||
```
|
||||
|
||||
Iniciar o frontend em modo dev:
|
||||
UI web servida pela extensão Pi (é o caminho que conversa com o runtime Pi de verdade):
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
npm run build # a extensão serve o dist/
|
||||
# com o Pi Agent carregando este repositório como pacote Pi (veja "pi" em package.json)
|
||||
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
|
||||
# abra http://127.0.0.1:58785
|
||||
```
|
||||
|
||||
Build:
|
||||
App desktop:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run tauri dev # janela de desenvolvimento, usa o servidor Vite
|
||||
npm run tauri build # empacota conforme src-tauri/tauri.conf.json (deb no Linux, dmg, nsis)
|
||||
```
|
||||
|
||||
Testes:
|
||||
Android (veja `scripts/dev-android.sh` e o job de Android no workflow de release):
|
||||
|
||||
```bash
|
||||
npm run test:run
|
||||
npm run tauri android dev
|
||||
```
|
||||
|
||||
Type checks:
|
||||
## Uso
|
||||
|
||||
Rotas locais expostas pelo servidor da extensão. Todas, exceto `/global/health` e a rota SSE, exigem o bearer token do arquivo de descoberta.
|
||||
|
||||
| Rota | Para que serve |
|
||||
|---|---|
|
||||
| `GET /global/health` | Prova de vida, responde `{"status":"ok","pi":"ready"}` |
|
||||
| `GET /global/event` | Stream SSE de eventos (sessões, partes de mensagem, status) |
|
||||
| `GET /api/models` | Lista de modelos com capacidades normalizadas |
|
||||
| `GET /api/sessions` | Lista de sessões |
|
||||
| `POST /api/sessions` | Cria sessão |
|
||||
| `POST /api/sessions/abort` | Aborta o turno em execução |
|
||||
| `GET /api/sessions/:id/messages` | Histórico da sessão normalizado para renderização |
|
||||
| `GET /api/sessions/:id/context` | Uso de contexto da sessão ativa |
|
||||
| `POST /api/messages/send` | Envia mensagem do usuário para uma sessão |
|
||||
| `GET /api/skills` | Skills efetivas agrupadas por origem |
|
||||
| `GET /api/mcp/status` | Servidores MCP configurados (transporte, comando, URL, origem) |
|
||||
| `GET /api/commands/list` | Slash commands built-in e dinâmicos |
|
||||
| `GET /api/agents`, `GET /api/files/list`, `GET /api/permissions/list`, `GET /api/questions/list` | Inventário do runtime para os painéis |
|
||||
| `GET /api/vcs/status`, `/info`, `/branches` | Estado do Git usado pelos controles do composer |
|
||||
| `GET /api/extensions/list` | Catálogo de extensões do painel de extensões |
|
||||
| `GET /api/settings/stt`, `/api/settings/tts` | Configurações de voz (STT/TTS) |
|
||||
| `GET /api/network/access`, `POST /api/network/access` | Chave de acesso em LAN (padrão: só loopback) |
|
||||
|
||||
A tabela completa de rotas, incluindo as mutações de Git e de extensões, está em [`extensions/piagentui-server.ts`](extensions/piagentui-server.ts). Portas e caminhos podem mudar; o arquivo de descoberta é a fonte de verdade para porta e token.
|
||||
|
||||
Auditar o agente pelo shell também funciona, por exemplo:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run typecheck:extensions
|
||||
TOKEN=$(node -e "console.log(require(process.env.HOME+'/.pi/agent/piagentui-port.json').token)")
|
||||
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:58785/api/models | head -c 300
|
||||
```
|
||||
|
||||
Validação completa:
|
||||
## Produção e deploy
|
||||
|
||||
```bash
|
||||
npm run validate
|
||||
npm run build # tsc -b && vite build; saída em dist/ (cerca de 14 MB, estático)
|
||||
npm run preview # serve o dist/ localmente para conferência final
|
||||
```
|
||||
|
||||
## Runtime da extensão Pi
|
||||
- Hospedagem estática: `dist/` é uma SPA comum. Se for montada em um subcaminho, build com `VITE_BASE_PATH=/subcaminho/ npm run build`.
|
||||
- Container (front end com Caddy): `docker/Dockerfile.frontend` builda a UI em Node 22 e serve pelo Caddy na porta 3000.
|
||||
- Stack completa de containers: `docker-compose.yml` sobe `gateway` (Caddy com o roteador Rust em 6658/6659), `frontend` e `backend`. Copie `.env.example` para `.env` antes. As imagens vêm de `ghcr.io/evandrodevbr/opencodeui-{backend,frontend,gateway}`, publicadas pelos workflows `docker-*`; para buildar localmente use `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`.
|
||||
- GitHub Pages: `.github/workflows/deploy.yml` builda o `dist/` com `VITE_BASE_PATH=/PiAgentUI/` e publica a cada push em `main` (na primeira vez, habilite o Pages com origem "GitHub Actions").
|
||||
- Releases desktop e mobile: `.github/workflows/release.yml` roda em tags `v*` e anexa artefatos de Windows, macOS, Linux e Android ao release do GitHub.
|
||||
|
||||
O PiAgentUI é registrado como extensão Pi em `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"extensions": ["./extensions/piagentui-server.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Quando a extensão inicia, ela escreve metadados de descoberta local em:
|
||||
## Estrutura do projeto
|
||||
|
||||
```text
|
||||
~/.pi/agent/piagentui-port.json
|
||||
extensions/ Extensão Pi: servidor HTTP/WebSocket, store de settings,
|
||||
gerentes de git e de extensões, todos com testes Vitest
|
||||
src/ Front end React (entrada Vite em index.html)
|
||||
├── api/ Clientes HTTP/SSE e pipeline de requisições
|
||||
├── components/ Peças de UI compartilhadas (code blocks, diffs, command palette)
|
||||
├── features/ chat, input, mensagens, ferramentas, sessões, settings, slash commands
|
||||
├── hooks/ sessão, eventos, transcrição, permissões
|
||||
├── locales/ 8 bundles traduzidos
|
||||
├── store/ Stores (sessões, mensagens, layout, tema)
|
||||
└── constants/ URL base da API, chaves de storage, métricas de UI
|
||||
src-router/ Roteador do gateway em Rust (axum), atrás do Caddy
|
||||
src-tauri/ Shell desktop e mobile Tauri 2 (Rust), projeto Android em gen/
|
||||
docker/ Dockerfiles, configs do Caddy, entrypoints
|
||||
scripts/ cópia de ícones, bump de versão, preparação de release, helper Android
|
||||
docs/superpowers/ Specs de design e planos escritos durante a migração
|
||||
```
|
||||
|
||||
O app web usa a porta/token desse arquivo para falar com o servidor local da extensão. Algumas mudanças de backend exigem reiniciar ou recarregar o processo da extensão Pi antes de aparecerem no browser.
|
||||
## Verificação
|
||||
|
||||
## Endpoints locais importantes
|
||||
Tudo abaixo foi executado em um clone limpo neste estado do repositório:
|
||||
|
||||
| Endpoint | Finalidade |
|
||||
| -------------------------------- | ----------------------------------------------------- |
|
||||
| `GET /api/models` | Lista real de modelos Pi com capacidades normalizadas |
|
||||
| `GET /api/sessions` | Lista de sessões lida dos arquivos de sessão do Pi |
|
||||
| `GET /api/sessions/:id/messages` | Histórico normalizado para renderização na UI |
|
||||
| `GET /api/sessions/:id/context` | Uso de contexto runtime para a sessão ativa |
|
||||
| `POST /api/messages/send` | Envia mensagem para a sessão Pi solicitada |
|
||||
| `GET /api/skills` | Skills efetivas do Pi agrupadas por origem |
|
||||
| `GET /api/mcp/status` | Metadados dos servidores MCP configurados |
|
||||
| `GET /api/commands/list` | Slash commands built-in e dinâmicos do Pi |
|
||||
| `GET /global/event` | Stream SSE de eventos do backend PiAgentUI |
|
||||
| Comando | Resultado |
|
||||
|---|---|
|
||||
| `npm ci` | 615 pacotes instalados, postinstall copia 266 ícones |
|
||||
| `npm run typecheck` | exit 0 (`tsc -b`, projetos app e extensão) |
|
||||
| `npm run typecheck:extensions` | exit 0 |
|
||||
| `npm run lint` | exit 0 (0 erros, 109 avisos) |
|
||||
| `npm run build` | exit 0, `dist/` com cerca de 14 MB |
|
||||
| `npm run test:run` | 89 arquivos, 319 testes, todos passando |
|
||||
| `npm run validate` | exit 0 (o mesmo gate que o CI roda em `build.yml`) |
|
||||
| `cargo check` em `src-router/` | exit 0 |
|
||||
| `cargo check --manifest-path src-tauri/Cargo.toml` | exit 0 (1 aviso) |
|
||||
| servidor da extensão via HTTP | `/global/health` 200, `/` 200 com `PI_BOOT_DATA`, `/api/models` 200 com token e 401 sem, `/api/sessions`, `/api/sessions/:id/messages`, `/api/sessions/:id/context`, `/api/skills`, `/api/mcp/status`, `/api/commands/list`, `/api/network/access` todos 200, `/global/event` 200 `text/event-stream` |
|
||||
|
||||
## Princípios de desenvolvimento
|
||||
Dois detalhes ao rodar a suíte: `npm run test:run` precisa do `dist/` existir, porque o teste do servidor da extensão busca o `index.html` servido, então `npm run build` deve rodar antes (é a ordem em `npm run validate`); e `npm run format:check` hoje acusa 67 arquivos fora do padrão do Prettier, então `npm run check` falha nesse passo mesmo com o gate do CI passando.
|
||||
|
||||
- Preferir dados reais do runtime Pi em vez de estado fake só da UI.
|
||||
- Manter OpenRouter como enriquecimento de catálogo, nunca como substituto da identidade provider/modelo do Pi.
|
||||
- Tratar valores runtime desconhecidos explicitamente.
|
||||
- Escrever testes antes de mudanças de comportamento sempre que possível.
|
||||
- Manter tool results dentro dos cards de ferramenta.
|
||||
- Seguir o sistema visual existente: tema, movimento, espaçamento e padrões de painéis.
|
||||
- Separar claramente o que está implementado do que é roadmap.
|
||||
## Estado atual e limitações
|
||||
|
||||
## Notas do repositório
|
||||
- Projeto ativo de um desenvolvedor, pré-1.0 (`0.6.10`). Chat, sessões, MCP, skills e painéis de comandos funcionam contra um runtime Pi real; algumas áreas ainda mudam rápido.
|
||||
- A herança de nomes da base OpenCodeUI foi limpa só em parte: o crate Rust se chama `opencodeui-router`, as imagens de container são `opencodeui-*`, os comentários do `.env.example` estão em chinês e a stack Docker roda um backend `opencode serve` que pertence ao deploy herdado, não ao fluxo da extensão Pi.
|
||||
- Não há teste do shell Tauri nem do gateway Rust além da compilação; os pacotes desktop e Android só são gerados pelo workflow de release.
|
||||
- A suíte é de componentes e de servidor; não há teste end-to-end de navegador nem limite de cobertura.
|
||||
- `@mariozechner/pi-coding-agent` é devDependency só para tipos (o runtime fornece a API real da extensão) e o npm marca essa linha como depreciada em favor de `@earendil-works/pi-coding-agent`.
|
||||
- O front end conversa com um runtime por janela: o arquivo de descoberta ou um servidor configurado à mão. Não há agregação de múltiplos runtimes.
|
||||
- A entrada de voz existe na UI (`src/hooks/useVoiceTranscription.ts`) e exige um endpoint STT compatível com OpenAI configurado nos settings; não há teste automatizado de navegador para ela.
|
||||
- Sem pacote publicado no npm e sem demo web hospedada; o README e o código assumem um runtime local.
|
||||
|
||||
O projeto ainda contém nomes herdados da base original OpenCodeUI em alguns pontos, incluindo metadados do pacote e documentação antiga. A direção atual é PiAgentUI-first, e uma limpeza futura deve migrar esses nomes sem quebrar os workflows locais.
|
||||
## Documentação
|
||||
|
||||
| Documento | Conteúdo |
|
||||
|---|---|
|
||||
| [`docs/superpowers/specs/`](docs/superpowers/specs/) | Specs de design da migração para extensão Pi, sessões, STT e controles de Git |
|
||||
| [`docs/superpowers/plans/`](docs/superpowers/plans/) | Planos de implementação e roadmap de contexto, skills e MCP |
|
||||
| [`CHANGELOG.md`](CHANGELOG.md) | Histórico de releases usado pelo workflow de release |
|
||||
| [`docker/`](docker/) | Dockerfiles, configs do Caddy e entrypoints da stack de containers |
|
||||
|
||||
## Licença
|
||||
|
||||
Este repositório segue a licença declarada em `package.json`: `GPL-3.0-only`.
|
||||
GPL-3.0-only, conforme `package.json` e [`LICENSE`](LICENSE). PiAgentUI é um fork e uma reescrita do OpenCodeUI; os autores originais estão creditados em `src-tauri/Cargo.toml`.
|
||||
Reference in new issue
Block a user