pigide

<div align="center"> <a href="https://kroch228.github.io/pigide-landing/"> <picture> <source srcset=".github/readme/hero.webp" type="image/webp"/> <img src=".github/readme/hero.gif" alt="PigIDE — Intent Into Motion" width="100%"/> </picture> </a> <br/> [](https://kroch228.github.io/pigide-landing/) [](LICENSE) [](#stack) [](#prerequisites) [](CODE_OF_CONDUCT.md) <br/> **A desktop IDE that hosts a pool of CLI coding agents as tiled terminal panes.** <br/>You direct. The swarm builds. Voice in. Code out. <br/> **→ <a href="https://kroch228.github.io/pigide-landing/">View the live landing page</a>** </div> --- ## Quickstart ```bash git clone https://github.com/<your-fork>/pigide cd pigide/frontend && pnpm install && cd ../src-tauri cargo tauri dev ``` Once the window is open: 1. **+** in the Workspaces sidebar — your first workspace. 2. **+ kiro-cli** (or any agent type) inside an empty TilingArea — terminal tile spawns with the agent already running. 3. Talk to the orchestrator on the right pane to dispatch tasks across tiles. 4. `Ctrl+,` opens Settings · `Ctrl+1..9` jumps between workspaces. For voice: hold the configured PTT hotkey (off by default — bind in `Settings → Voice`) and speak. Partials stream into the focused input within 300 ms. <div align="center"> <img src=".github/readme/stats.svg" alt="6 agent runtimes · 300 ms voice latency · 120k GPU particles · 100% local" width="100%"/> </div> <br/> <div align="center"> <img src=".github/readme/marquee.svg" alt="Conduct the swarm · You direct · Agents build" width="100%"/> </div> <br/> ## Stack - **Rust core (Tauri 2):** `portable-pty`, `rusqlite`, `reqwest`, `tokio`, `cpal`, `whisper-rs` - **Frontend (React + TypeScript + Vite):** `allotment`, `@xterm/xterm`, `zustand` ## Prerequisites - Rust 1.80+ (`rustc 1.95` tested) - Node 20+ + pnpm 9+ (`node 25`, `pnpm 10` tested) - Linux: `webkit2gtk-4.1` and PulseAudio/ALSA dev libs - An OmniRouter instance running locally (defaults to `http://localhost:20128`) - `~/.local/bin/kiro-cli` and `/usr/bin/claude` for the agent tiles <br/> ## Build <details> <summary><b>Development run</b> — <code>cargo tauri dev</code></summary> ```bash # Install frontend deps cd frontend pnpm install cd .. # Run the dev server (Vite) + Tauri window cd src-tauri cargo tauri dev # (or, if @tauri-apps/cli is installed in frontend/, `pnpm tauri dev` from frontend/) ``` </details> <details> <summary><b>Release build</b> — <code>./scripts/build.sh</code></summary> Script builds frontend and Tauri app, automatically selects Whisper backend (GPU/CPU) and puts everything into `./dist/` in the repository root. ```bash ./scripts/build.sh ``` What's included in `dist/`: ``` dist/ ├── bin/ # raw executables (pigide, pigide-cli) ├── bundle/ # installers (.deb / .rpm / .AppImage / .dmg / .msi) └── BUILD_INFO.txt # date, commit, used GPU backend ``` GPU backend is determined automatically (CUDA → ROCm → Vulkan → CPU; on macOS — Metal). Can be forced via `PIGIDE_GPU`: ```bash PIGIDE_GPU=cuda ./scripts/build.sh # NVIDIA, requires CUDA toolkit PIGIDE_GPU=hipblas ./scripts/build.sh # AMD ROCm PIGIDE_GPU=vulkan ./scripts/build.sh # cross-vendor Vulkan PIGIDE_GPU=metal ./scripts/build.sh # Apple Silicon PIGIDE_GPU=cpu ./scripts/build.sh # CPU-only ``` At runtime, can force CPU without rebuilding: `PIGIDE_WHISPER_CPU=1`. Before building, script shows **preflight**: current branch, commit, ahead/behind relative to `origin/main`, and list of uncommitted changes. If working tree is dirty — asks for confirmation (this is insurance against situation when you forgot to commit and then lost edits on checkout). To skip question in CI: `PIGIDE_BUILD_DIRTY=1 ./scripts/build.sh`. </details> <details> <summary><b>First-run notes</b> — where data, logs, and models live</summary> - Database: `~/.config/pigide/db.sqlite` - Whisper model: downloaded on first PTT use to `~/.cache/pigide/ggml-small.bin` - Logs: stderr, set `RUST_LOG=pigide=debug,info` </details> <br/> ## Architect model The Kiro orchestrator runs against a swappable LLM backend. Default is the **Anthropic Messages API** with **Claude Opus 4.5** as primary and **Claude Opus 4** as automatic fallback on `5xx` / `529` / timeout. Set `ANTHROPIC_API_KEY` in the environment, or paste a key into `Right pane → Settings → API key`. OmniRouter (OpenAI-compatible) remains available — switch via `Right pane → Settings → Provider`. <br/> ## Watcher (optional) <details> <summary>Background supervisor of agent stdout on Gemini Flash-Lite</summary> Watcher listens to stdout of each spawned agent, classifies chunks via Google AI Studio Generative Language API (by default `gemini-2.5-flash-lite` — Gemma 3 4B IT from the initial AI Studio v1beta brief no longer returns; live testing showed that Gemma 4 31B goes into reasoning-prose instead of strict JSON, and Flash-Lite provides strict-JSON and costs ~10× less) and escalates "questions to human" to Architect's mailbox `role:coordinator`, on thread `watcher:<agent_id>`. Architect's response is automatically injected back into stdin of the original agent — the agent does not hang on interactive prompt while you approach. ### Enable Build-time option: ```bash cd src-tauri cargo build --features watcher # or for debug-run GEMINI_API_KEY=AIzaSy... cargo tauri dev --features watcher ``` Without `GEMINI_API_KEY`, Watcher silently disables on startup (one warning line in logs) — the rest of the app works as usual. ### Environment variables | Variable | Default | Purpose | |-|-|-| | `GEMINI_API_KEY` | — (required) | Google AI Studio key. Only goes into `x-goog-api-key` header, not into URL or logs. | | `PIGIDE_WATCHER_RPM` | `10` | Per-agent rate-limit (requests per minute). Token-bucket: if overflowed, chunk is dropped, not queued. | | `PIGIDE_WATCHER_MODEL` | `gemini-2.5-flash-lite` | Name of Generative Language API model. Change if your key has access to another Gemma/Gemini-Flash-Lite. | ### MCP tool When Watcher is active, MCP server registers one new tool: ```json { "method": "tools/call", "params": { "name": "watcher_status", "arguments": {} } } ``` Returns `{enabled, rpm, agents: { <agent_id>: {last_classification, calls_this_minute, blocked_until, dropped} }}` — convenient for dashboards and checking that bucket is not stuck. ### Cost `gemini-2.5-flash-lite` is available in free-tier AI Studio with per-project limit around 30 RPM per key (at the time of writing). Default `PIGIDE_WATCHER_RPM=10` is chosen so that one agent does not eat up the key limit alone. On paid tiers, Flash-Lite is the cheapest Gemini API model, ~$0.075 per 1M input tokens and $0.30 per 1M output tokens (text). </details> <br/> ## PigVoice — instant voice-to-text <details> <summary>Streaming voice layer · sub-300 ms perceived latency · LocalAgreement-2 merger</summary> PigVoice is the streaming voice layer baked into PigIDE. Goal: **sub-300 ms perceived latency** from speech to first visible token, with partial hypotheses dropped straight into the focused input. ### How it works ``` mic (cpal) → resample 16k → Silero-style VAD → rolling-window Whisper → LocalAgreement-2 merger → voice://partial events → on VAD endpoint: clean final → voice://final ``` The on-device engine is `whisper.cpp` (via `whisper-rs`, no new native deps). Partials are stabilised with **LocalAgreement-2**: a token only commits to the visible UI once two successive decoding passes agree on it, so the text never wobbles backwards. See [`PIGVOICE_RESEARCH.md`](./PIGVOICE_RESEARCH.md) and [`PIGVOICE_PLAN.md`](./PIGVOICE_PLAN.md) for the full design. </details> ### Settings (in `~/.config/pigide/db.sqlite`, table `settings`) | key | default | meaning | |-|-|-| | `voice.partial_enabled` | `true` | turn streaming partials on/off (falls back to batch) | | `voice.partial_hop_ms` | `250` | re-decode cadence while in a speech segment | | `voice.endpoint_silence_ms` | `400` | silence required to commit a final segment | | `voice.engine` | `whisper-streaming` | `whisper-streaming` / `whisper-batch` / `deepgram` (cloud, opt-in) | | `voice.cloud_api_key` | unset | Deepgram Nova-3 key (kept in user settings, never written to git) | | `voice.cloud_endpoint` | Deepgram default | overrideable WS endpoint | | `voice.hotkey_enabled` | `false` | global PTT hotkey (off by default; conflicts with WMs) | | `voice.record_mode` | `push-to-talk` | or `toggle` | | `voice.inject_enabled` | `false` | type final transcript into the focused window | | `whisper.model_id` | `small` | one of `tiny` / `base` / `small` / `medium` / `large` / `distil-large` | | `whisper.language` | `auto` | Whisper language hint | The streaming path defaults to `tiny` for first-token speed; pick a larger model from the in-app voice settings panel for better accuracy. If the model isn't downloaded yet, the streaming loop quietly no-ops and the existing batch path triggers a download on `stop`. ### GPU acceleration (optional) By default PigIDE builds Whisper CPU-only. The release build script (`./scripts/build.sh`) automatically determines GPU; to choose manually, export `PIGIDE_GPU=cuda|hipblas|vulkan|metal|cpu` — see the [Build](#build) section. Whisper context tries GPU and falls back to CPU with a `warn!` log if initialization fails (no toolkit, no device, OOM, etc.). At runtime, force CPU with `PIGIDE_WHISPER_CPU=1`. System dependencies by backend: - `gpu-cuda` — CUDA toolkit (cublas, cudart, nvcc). Arch: `sudo pacman -S cuda`. Ubuntu: `sudo apt install nvidia-cuda-toolkit`. - `gpu-hipblas` — AMD ROCm. - `gpu-vulkan` — Vulkan SDK. - `gpu-metal` — Apple Silicon, nothing to install. Verify the live backend in logs (`RUST_LOG=pigide=info`): ``` whisper: GPU backend initialized (model=small) ``` ### Events (Tauri) | event | payload | when | |-|-|-| | `voice://state` | `{ state: "idle" \| "recording" \| "transcribing" }` | start/stop | | `voice://partial` | `{ stable, unstable, segment_id }` | every `partial_hop_ms` mid-segment | | `voice://final` | `{ text, segment_id }` | VAD endpoint or user stop | | `voice://transcript` | `{ text }` | back-compat alias of `final` | | `voice://engine-error` | `{ engine, error }` | non-fatal engine failure | | `voice://download` | `{ bytes, total }` | model download progress | ### Tests ```bash cd src-tauri # unit tests for the merger, VAD, mode controller, cloud config, etc. cargo test --lib voice:: # end-to-end streaming integration test (no mic / no model needed): cargo test --test integration_streaming # latency benchmark — fails if median first-partial > 600 ms: cargo test --test bench_latency --release ``` <br/> ## Skills — extensible Architect prompt-modules <details> <summary>Auto-discovered YAML modules · hot-reload · per-turn injection</summary> The Architect's prompt is no longer fixed. **Skills** are small named `.md` modules with a YAML frontmatter that the Architect auto-discovers from `~/.pigide/skills/` and `<workspace>/.pigide/skills/` and selects per turn (by tags / triggers / explicit `@skill:<id>` mention). ```markdown --- id: builder-brief-writer name: Builder Brief Writer description: Writes a self-contained brief for a Builder agent priority: 60 tags: [dispatch, builder] triggers: [builder] --- You are composing a Builder brief. GOAL: {{goal}} {{#if files_in_scope}}FILES: {{files_in_scope}}{{/if}} ``` Five built-ins ship by default — including `user-skill-prompt-engineer`, the meta-skill the Architect invokes whenever it's about to dispatch to a sub-agent. The Skills panel (right pane → Skills) lists everything, toggles enable/disable, shows the last turn's selection trace, and lets you stub a new user skill from the UI. The Architect prompt itself (`src-tauri/src/orchestrator/prompt.rs`, v2 — gold-standard meta-prompting; v1 archived alongside as `prompt.v1.rs`) drives every turn through a deterministic 8-step pipeline: **intent → contract** (role / goal / exit_criteria) → **skill selection** → **memory grounding** → **decomposition** (Plan-and-Solve / Least-to-Most) → **draft** (via `[[user-skill-prompt-engineer]]`) → **self-critique** (Self-Refine + Chain-of-Verification) → **dispatch** (parallel where independent) → **observe + self-improve** (`create_memory` for new patterns). Research citations are at the top of `prompt.rs`. See the built-in skills in `src-tauri/resources/skills/` for examples. ```bash # unit tests (parser, router, composer, registry) cargo test --lib skills:: # integration test (end-to-end compose + hot-reload) cargo test --test skills_integration ``` </details> <br/> ## Acknowledgements PigIDE integrates third-party software whose licenses are reproduced in `LICENSES/` and summarised in [`NOTICE`](./NOTICE): - **[Ruflo](https://github.com/ruvnet/ruflo)** (MIT, 2024-2026 ruvnet) — used as a supervised Node.js sidecar (`pigide-ruflod`) that powers the orchestrator-ledger layer. PigIDE talks to it over its MCP server (transport=stdio); see `src-tauri/src/ruflo/` for the bridge. <br/> <div align="center"> _{2026 PigIDE · Tauri · React · Rust · Three.js · <b>local · forever</b>} <br/> _{<a href="https://kroch228.github.io/pigide-landing/">kroch228.github.io/pigide-landing</a>} </div>