⚡ PIA (Programmable Intelligence Agent)

A blazing-fast, lean, pure native terminal coding agent built in 100% Rust. Engineered for minimal memory footprint, zero runtime overhead, and a distraction-free developer experience.

🎯 Core Principles

Pia is engineered from the ground up to replace heavy, sluggish web-based coding agents with a pure, lightweight, native terminal tool that stays out of your way and respects your system resources.

       ┌────────────────────────────────────────────────────────┐
       │                       Pia Agent                        │
       │   Pure Native Rust  •  Instant (<15ms)  •  Zero VM     │
       └───────────────────────────┬────────────────────────────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
   Native TUI & Inline      Unified Providers       Embedded Extensions
    Markdown Streaming       & Local Proxies         & Agent Skills

• 🦀 Pure Native Rust & Predictable Resource Footprint:
  • Zero VM or runtime overhead: Single native binary without Node.js, Python virtual environments, or Electron bloat.
  • Instant cold startup in < 15ms; launches immediately into the prompt without runtime spin-up latency.
  • Bounded Streaming Architecture: Streaming buffers and output pipes are bounded with early cutoff limits (50KB cap on read/bash, line-buffered grep, streaming JSONL) preventing heap churn and memory runaway during marathon sessions. Memory usage scales strictly with active LLM context rather than runtime VM garbage collection.
• ✨ Pure, Distraction-Free Terminal Experience:
  • Pristine Opening Prompt: Opens directly into the active prompt without noisy greeting banners, update nag screens, or historical session clutter.
  • Silent & Graceful Interruption: Hitting Ctrl+C or Esc immediately cancels running streams, kills child subprocesses (kill_on_drop(true)), drains input buffers, clears the overlay, and returns cleanly to an idle prompt without screaming red logs or terminal corruption.
  • Inline Differential Streaming: Runs directly within your terminal stream (termimad). Never hijacks your screen into an alternate screen buffer, preserving native scrollback, mouse selection, and terminal multiplexer workflows (tmux, zellij).
  • Invariant Bottom Composer: An interactive prompt docked at the terminal base remains responsive and writable even while reasoning models are thinking or tools are executing.
  • Terminal Zoom & IME Stability: Zero cursor drift or staircasing artifacts when resizing terminal windows or composing text with Vietnamese IME (Telex/VNI).
• 🧱 Modular Layered Architecture:
  • Strictly decoupled Cargo workspace: platform-independent core, pluggable LLM providers, sandboxable tools, embedded scripting, and native TUI.
• 🔌 First-Class Local AI Proxy Integration:
  • Zero-config compatibility with local proxies: CLIProxyAPI (http://127.0.0.1:8317/v1) and OmniRoute (http://127.0.0.1:20128/v1), alongside direct Anthropic, OpenAI, and Google Gemini.
  • Hierarchical model discovery in ./.pia/models.json and ~/.pia/models.json.
• ⚡ Procedural Agent Skills Catalog:
  • Structured Agent Skills format (SKILL.md) discovered strictly from .pia/skills/ (workspace) and ~/.pia/skills/ (user-global).
  • Integrated into the interactive slash menu: /skill:<name> items match any keyword dynamically.
  • Direct execution with inline instructions: /skill <name> [instructions] or direct alias /custom-skill [instructions].
• 🛡️ Tiered Security & Safe Guardrails:
  • Mutating operations (write, edit, bash) display colored diffs and prompt for approval ([y] Yes / [n] No / [a] Always approve).
  • 5-option tiered external path access dialog (Allow Once, Allow for Session, Save to Workspace, Save to Global System, Deny).
  • Subprocess kill_on_drop(true) ensures background shell commands are reliably killed when interrupted.
  • Read tools cap output safely at 2,000 lines / 50KB with pagination hints (offset), while glob automatically excludes bulky build directories (target/, .git/, node_modules/).
• 📥 Concurrent FIFO Input Queueing:
  • Type prompts or queue slash commands (e.g. /compact) while the agent is streaming or executing tools.
• 🖼️ Clipboard Image Paste & Multimodal Vision:
  • Instant image paste from clipboard via Ctrl+V (or Alt+V on Windows/WSL) using native arboard (macOS, Windows, Wayland, X11).
  • Drag-and-drop / pasted path detection: converts pasted image file paths into tokens [image: <path>].
  • Multimodal vision delivery: auto-downscales oversized screenshots and delivers base64 image blocks to vision-capable models.
• 🧠 Persistent Multi-Scope Memory:
  • Built-in multi-scope store (user, project, memory, failure) and automatic workspace context discovery (AGENTS.md / CLAUDE.md).
• 🧩 Embedded Rhai Script Extensions:
  • Extend Pia with custom tools and lifecycle hooks (before_tool, after_tool, on_message) using lightweight Rhai scripts without external interpreters.

🏗️ Architecture Overview

Pia is structured as a modular Cargo workspace:

pia/
├── crates/
│   ├── pia-core/        # Domain types, SessionTree, Skills manager, MemoryStore,
│   │                    # ModelsConfig, Settings, Context discovery, Git branch detector.
│   ├── pia-providers/   # Unified LLM provider trait, SSE streaming parsers (Anthropic,
│   │                    # OpenAI-compatible, Gemini), Local proxy integrations.
│   ├── pia-tools/       # Built-in tools (read, write, edit, bash, glob, grep, memory, skill),
│   │                    # Security path policy, unified diffs, artifact store.
│   ├── pia-extensions/  # Embedded Rhai scripting engine & lifecycle hook dispatcher.
│   ├── pia-tui/         # Native TUI, ANSI themes, termimad markdown renderer, LineEditor,
│   │                    # WorkingOverlay, Braille spinner, slash menus, Tab autocomplete.
│   └── pia/             # Agent orchestrator, concurrent input queue, CLI entrypoint.
├── scripts/             # Standalone installation scripts (install.sh).
└── assets/              # Identity assets (icon.svg, icon-monochrome.svg, icon-symbol.svg).

🚀 Installation & Quick Start

1. One-Line Shell Installer (macOS & Linux)

The easiest way to install Pia. Downloads and extracts the latest precompiled release binary to ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/pia-labs/pia/main/scripts/install.sh | sh

2. Install via Cargo

# Install directly from GitHub
cargo install --git https://github.com/pia-labs/pia.git pia --force

3. Prebuilt Binaries (Direct Download)

Download standalone binaries from GitHub Releases:

4. Build from Source

# Clone the repository
git clone https://github.com/pia-labs/pia.git
cd pia

# Build release binary
cargo build --release

# Install locally to ~/.cargo/bin
cargo install --path crates/pia --force

📋 Prerequisites & Provider Setup

Pia works out of the box with any of the following:

1. Local AI Proxies (Recommended for Zero Token Friction)

• CLIProxyAPI running at http://127.0.0.1:8317/v1.
• OmniRoute running at http://127.0.0.1:20128/v1.

2. Direct Cloud APIs

Export your API keys in your shell:

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."
# or
export GEMINI_API_KEY="AIza..."

⌨️ Basic Usage & Slash Commands

# Start an interactive session in current workspace
pia

# Continue previous session in this workspace
pia -c

# Resume a specific session (or open picker)
pia -r

# Start with a specific model
pia --model gemini-3.8-flash-high

# Run with light theme
pia --theme light

# One-shot prompt execution
pia -p "Analyze current workspace health and list tests"

# Autonomous mode (skip mutating tool confirmation dialogs)
pia --auto-approve

Interactive Slash Commands

Type / at the prompt to trigger the fuzzy slash menu:

⚙️ Configuration & Model Discovery

Pia discovers LLM model endpoints in order:

1. ./.pia/models.json (Workspace configuration)
2. ~/.pia/models.json (User-global configuration)

Sample ~/.pia/models.json:

{
  "providers": {
    "cliproxyapi": {
      "baseUrl": "http://127.0.0.1:8317/v1",
      "apiKey": "none",
      "apiType": "openai",
      "models": [
        { "id": "gemini-3.8-flash-high", "name": "Gemini 3.8 Flash High", "contextWindow": 1048576 },
        { "id": "claude-3-7-sonnet", "name": "Claude 3.7 Sonnet", "contextWindow": 200000 }
      ]
    }
  }
}

🧩 Rhai Script Extensions

Drop .rhai files into .pia/extensions/ or ~/.pia/extensions/:

// .pia/extensions/custom_tools.rhai
register_tool(
    "echo_reverse",
    "Reverses an input string",
    #{ "type": "object", "properties": #{ "input": #{ "type": "string" } }, "required": ["input"] },
    |args| {
        let text = args.input;
        "Reversed: " + text
    }
);

Hook into agent lifecycle events:

• before_tool(name, input): Inspect or veto tool execution.
• after_tool(name, result): Transform or log results.
• on_message(role, content): Inspect messages before submission.

🧪 Testing & Quality Gates

Pia maintains strict test-driven development and zero-warning standards:

# 1. Run the entire automated test suite (135 tests across all crates)
cargo test --workspace

# 2. Run TUI-specific tests
cargo test -p pia-tui

# 3. Check for Clippy linter warnings (strict zero-tolerance)
cargo clippy --all-targets -- -D warnings

# 4. Check Rust formatting compliance
cargo fmt --check

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.