--- slug: "vtstech-pi-security" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/VTSTech/pi-coding-agent@main/README.md" repo: "https://github.com/VTSTech/pi-coding-agent" source_file: "README.md" branch: "main" ---
# ⚡ Pi Coding Agent - VTSTech's Extensions **Pi package with custom extensions, themes, and configurations for the [Pi Coding Agent](https://github.com/badlogic/pi-mono)** [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Pi Version](https://img.shields.io/badge/Pi-v0.66%2B-green.svg)](https://github.com/badlogic/pi-mono) [![Pi Package](https://img.shields.io/badge/Install-pi%20install%20git-blue.svg)](#installation) [![Version](https://img.shields.io/badge/Version-v1.3.9-orange.svg)](CHANGELOG.md)

VTSTech • Website • Extensions • Themes • Install

--- ## Overview A [Pi package](#pi-package-format) containing extensions, themes, and configuration for the [Pi Coding Agent](https://github.com/badlogic/pi-mono). These tools are built and optimized for running Pi on **resource-constrained environments** such as **Google Colab (CPU-only, 12GB RAM)** with **Ollama** serving small local models (0.3B-2B parameters), as well as with **cloud providers** like OpenRouter, Anthropic, Google, OpenAI, Groq, DeepSeek, and more. Everything here is battle-tested on real hardware with real models - from small local Ollama models on budget machines to cloud providers via OpenRouter. --- ## Installation ### Pi Package (recommended) ```bash pi install git:github.com/VTSTech/pi-coding-agent ``` Pi clones the repo, auto-discovers the `extensions/` and `themes/` directories, and loads everything automatically. Restart Pi and you're done. Update to the latest version: ```bash pi update ``` Pin to a specific tag: ```bash pi install git:github.com/VTSTech/pi-coding-agent@v1.3.0 ``` ### Individual Packages (npm) Install only what you need. Each extension is published as a standalone npm package under the `@vtstech` scope. All shared code is bundled into each package, so there are no extra dependencies to install. ```bash # Install individual extensions pi install npm:@vtstech/pi-diag pi install npm:@vtstech/pi-hex-edit pi install npm:@vtstech/pi-model-test pi install npm:@vtstech/pi-security pi install npm:@vtstech/pi-soul pi install npm:@vtstech/pi-status pi install npm:@vtstech/pi-api pi install npm:@vtstech/pi-ollama-sync pi install npm:@vtstech/pi-openrouter-sync pi install npm:@vtstech/pi-react-fallback pi install npm:@vtstech/pi-long-term-memory # Update installed packages pi update ``` **Available packages:** | Package | Description | |---------|-------------| | `@vtstech/pi-diag` | System diagnostic suite | | `@vtstech/pi-model-test` | Model benchmark - Ollama & cloud providers | | `@vtstech/pi-security` | Command/path/SSRF protection | | `@vtstech/pi-soul` | SoulSpec persona management | | `@vtstech/pi-status` | System resource monitor & status bar | | `@vtstech/pi-api` | API mode switcher | | `@vtstech/pi-ollama-sync` | Ollama ↔ models.json sync | | `@vtstech/pi-openrouter-sync` | OpenRouter → models.json sync | | `@vtstech/pi-react-fallback` | ReAct fallback for non-native tool models | | `@vtstech/pi-long-term-memory` | Persistent memory across sessions | | `@vtstech/pi-hex-edit` | Hex stream-based edit replacement for reliable file editing | | `@vtstech/pi-workspace` | Workspace management and state persistence | ### Manual Install ```bash git clone https://github.com/VTSTech/pi-coding-agent.git cd pi-coding-agent cp extensions/*.ts ~/.pi/agent/extensions/ cp themes/*.json ~/.pi/agent/themes/ pi -c ``` ### Prerequisites - [Pi Coding Agent](https://github.com/badlogic/pi-mono) v0.66+ installed - [Ollama](https://ollama.com) running locally or on a remote machine (for Ollama features) - API key for any supported cloud provider (for cloud provider features) --- ## Pi Package Format This repo is a standard Pi package. The `package.json` contains a `pi` manifest that tells Pi where to find resources: ```json { "name": "@vtstech/pi-coding-agent-extensions", "version": "1.3.8", "keywords": ["pi-package"], "pi": { "extensions": ["./extensions"], "themes": ["./themes"] } } ``` Pi auto-discovers from conventional directories (`extensions/`, `themes/`, `skills/`, `prompts/`) even without the manifest. The manifest is included for explicit declaration. --- ## 🔌 Remote Ollama Support All extensions support **remote Ollama instances** out of the box - no extra configuration needed. The Ollama URL is resolved automatically from `models.json`: ``` models.json ollama provider baseUrl → OLLAMA_HOST env var → http://localhost:11434 ``` This means you can: - Run Ollama on a separate machine and tunnel it (e.g., Cloudflare Tunnel, Tailscale, SSH) - Use `/ollama-sync https://your-tunnel-url` to sync models from a remote instance - The sync writes the remote URL back into `models.json` so all other extensions (`model-test`, `status`, `diag`) automatically use it - Set `OLLAMA_HOST` as an environment variable fallback if no `models.json` config exists --- ## ☁️ Cloud Provider Support Model testing and diagnostics work with **cloud providers** out of the box. The extensions auto-detect the active provider and adapt their behavior: **Supported providers** (built-in registry): | Provider | API Mode | Base URL | |----------|----------|----------| | OpenRouter | openai-completions | `https://openrouter.ai/api/v1` | | Anthropic | anthropic-messages | `https://api.anthropic.com` | | Google | gemini | `https://generativelanguage.googleapis.com` | | OpenAI | openai-completions | `https://api.openai.com/v1` | | Groq | openai-completions | `https://api.groq.com` | | DeepSeek | openai-completions | `https://api.deepseek.com` | | Mistral | openai-completions | `https://api.mistral.ai` | | xAI | openai-completions | `https://api.x.ai` | | Together | openai-completions | `https://api.together.xyz` | | Fireworks | openai-completions | `https://api.fireworks.ai/inference/v1` | | Cohere | cohere-chat | `https://api.cohere.com` | Provider detection uses a three-tier lookup: user-defined providers in `models.json` → built-in provider registry → unknown fallback. --- ## Extensions ### 🔍 Diagnostics (`diag.ts`) **Run a full system diagnostic of your Pi environment.** ``` /diag # Run full system diagnostic /diag --help # Show help /diag --full-prompt # Show full untruncated system prompt ``` Checks: - **System** - OS, CPU, RAM usage, uptime, Node.js version - **Disk** - Disk usage via `df -h` - **Ollama** - Running? Version? Response latency? Models pulled? Currently loaded in VRAM? - **models.json** - Valid JSON? Provider config? Models listed? Cross-references with Ollama - **Settings** - settings.json exists? Valid? - **Extensions** - Extension files found? Active tools? - **Themes** - Theme files? Valid JSON? - **Session** - Active model? API mode? Provider? Base URL? Context window? Context usage? Thinking level? - **Security** - Active security mode, effective blocklist sizes (mode-aware), command/SSRF/path validation tests, audit log status Also registers a `self_diagnostic` tool so the AI agent can run diagnostics on command. ### 🧪 Model Benchmark (`model-test.ts`) **Test any model for reasoning, tool usage, and instruction following - works with Ollama and all cloud providers (OpenRouter, OpenAI, Anthropic, etc.).** ```bash /model-test # Test current Pi model /model-test qwen3:0.6b # Test a specific Ollama model /model-test --all # Test every Ollama model ``` The extension runs the **extended test flow** with 20 reasoning puzzles, multi-step JSON instruction compliance, and chained tool call generation. #### Test Suite (3 tests) | Test | Method | Scoring | |------|--------|---------| | **Reasoning** | 20 puzzle tests (logic, math, spatial, commonsense, counter-intuitive, causal, comparative, analogical) | STRONG / MODERATE / WEAK / FAIL / ERROR | | **Instructions** | Multi-step JSON schema compliance with automatic repair | STRONG / MODERATE / WEAK / FAIL | | **Tool Usage** | Chained tool call generation | STRONG / MODERATE / WEAK / FAIL / ERROR | Features: - **Extended reasoning test** - 20 diverse puzzles with detailed breakdown - **Multi-step instructions** - JSON schema with multiple fields and types - **Chained tool calls** - tests multi-tool invocation capability - **Automatic provider detection** - classifies the active model as `ollama`, `builtin`, or `unknown` - **Cloud provider support** - works with OpenRouter, OpenAI, Anthropic, and 11+ built-in providers - **Progress indicators** - UI notifications during testing - **No rate limit delay** - faster execution for Ollama instances - Tab-completion for model names in the `/model-test` command Features: - **Automatic provider detection** - classifies the active model as `ollama`, `builtin`, or `unknown` - **Extended reasoning test** - 20 diverse puzzles with detailed breakdown - **Multi-step instructions** - JSON schema with multiple fields and types - **Chained tool calls** - tests multi-tool invocation capability - **Built-in provider registry** - 11 known cloud providers with API modes and base URLs - **Automatic remote Ollama URL** - reads from `models.json`, no manual config - **Timeout resilience** - 180s default with `--connect-timeout`, auto-retry on failures - **Rate limit delay** - configurable delay between tests - **Thinking model fallback** - retries with `think:true` for models like qwen3 - **Displays API mode** - shows the active API mode from `models.json` - **Native context length** - displays true max context from Ollama `/api/show` - **Tool support cache** - persistent cache avoids re-probing on every run - **Text-based tool call detection** - handles models that output JSON as text - **JSON repair** - automatically fixes truncated output - Tab-completion for model names in the `/model-test` command - Final recommendation: STRONG / GOOD / USABLE / WEAK Sample output (cloud provider): ``` [model-test-report] ⚡ Pi Model Benchmark v1.3.3 Written by VTSTech GitHub: https://github.com/VTSTech Website: www.vts-tech.org (http://www.vts-tech.org) ── MODEL: poolside/laguna-xs.2:free ──────────────────────── ℹ️ Provider: openrouter (builtin) ── REASONING TEST (EXTENDED) ─────────────────────────────── i️ Testing 20 reasoning puzzles... i️ Waiting 10.0s to avoid rate limiting... ✅ ✅ snail_wall (logic): STRONG - expected "8", got "8" [(expected: 8, got: 8)] ✅ ✅ math_sequence (math): STRONG - expected "162", got "162" [(expected: 162, got: 162)] ✅ ✅ spatial_directions (spatial): STRONG - expected "south", got "180" [(expected: south)] ⚠️ ❌ commonsense (commonsense): WEAK - expected "the other side", got "?" [(expected: the other side)] ❌ ❌ code_simplify (code): FAIL - expected "15", got "2" [(expected: 15, got: 2)] ✅ ✅ bat_and_ball (counterint): STRONG - expected "5", got "5" [(expected: 5, got: 5)] ✅ ✅ scale_weight (counterint): STRONG - expected "400", got "400" [(expected: 400, got: 400)] ✅ ✅ syllogism (logic): STRONG - expected "warm-blooded", got "?" [(expected: warm-blooded)] ✅ ✅ if_then_chain (logic): STRONG - expected "grass grows", got "1" [(expected: grass grows)] ✅ ✅ cause_effect (causal): STRONG - expected "grows", got "?" [(expected: grows)] ✅ ✅ relative_quantities (comparative): STRONG - expected "15", got "15" [(expected: 15, got: 15)] ⚠️ ❌ analogy_1 (analogy): WEAK - expected "room", got "?" [(expected: room)] ✅ ✅ analogy_2 (analogy): STRONG - expected "boot", got "?" [(expected: boot)] ✅ ✅ physics_1 (commonsense): STRONG - expected "bowling ball", got "80" [(expected: bowling ball)] ⚠️ ❌ physics_2 (commonsense): WEAK - expected "hot", got "?" [(expected: hot)] ✅ ✅ objects_1 (commonsense): STRONG - expected "scissors", got "?" [(expected: scissors)] ✅ ✅ social_1 (commonsense): STRONG - expected "polite", got "?" [(expected: polite)] ✅ ✅ animals_1 (commonsense): STRONG - expected "water", got "?" [(expected: water)] ✅ ✅ gk_1 (commonsense): STRONG - expected "mars", got "?" [(expected: mars)] ✅ ✅ gk_2 (commonsense): STRONG - expected "366", got "366" [(expected: 366, got: 366)] ✅ Average score: STRONG ── INSTRUCTION FOLLOWING TEST (EXTENDED) ─────────────────── i️ Testing multi-step JSON schema compliance... i️ Waiting 10.0s to avoid rate limiting... i️ Time: 1.4s ✅ JSON output valid with correct values (STRONG) i️ Output: {"name":"Poolside Assistant","can_count":true,"sum":42,"language":"English","colors":["red","blue","green"],"timestamp":"2025-01-09T1 2:00:00Z"} ── TOOL USAGE TEST (EXTENDED) ────────────────────────────── i️ Testing chained tool calls... i️ Waiting 10.0s to avoid rate limiting... i️ Time: 349ms ✅ Tool calls: get_weather (MODERATE) i️ Response: I'll get the weather for Tokyo and calculate that multiplication for you. ── SUMMARY ───────────────────────────────────────────────── ✅ Reasoning: STRONG ✅ Instructions: STRONG ✅ Tool Usage: MODERATE i️ Total time: 1.3m i️ Score: 3/3 tests passed i️ Detailed: Reasoning 16/20 tests passed, Instructions 1/1, Tool Usage 1/1 ── RECOMMENDATION ────────────────────────────────────────── ❌ poolside/laguna-xs.2:free is WEAK - limited capabilities for agent use ``` ### 🔀 API Mode Switcher (`api.ts`) **Runtime switching of API modes, base URLs, thinking settings, and compat flags in `models.json`.** Supports all 10 Pi API modes: `anthropic-messages` · `openai-completions` · `openai-responses` · `azure-openai-responses` · `openai-codex-responses` · `mistral-conversations` · `google-generative-ai` · `google-gemini-cli` · `google-vertex` · `bedrock-converse-stream` ```bash /api # Show current provider config (mode, URL, compat flags) /api mode # Switch API mode (partial match supported) /api url # Switch base URL /api think on|off|auto # Toggle thinking for all models in provider /api compat # View compat flags /api compat # Set compat flag /api modes # List all 10 supported API modes /api providers # List all configured providers /api reload # Hint to run /reload ``` **Features:** - **Partial mode matching** - `/api mode openai-r` matches `openai-responses` - **Auto-detect local provider** - targets the first `localhost`/`ollama` provider by default - **Batch thinking toggle** - set `reasoning: true/false` across all models at once - **Compat flag management** - get/set `supportsDeveloperRole`, `thinkingFormat`, `maxTokensField`, etc. - Tab-completion for sub-commands ### 🔒 Security (`security.ts`) **Command, path, and network security layer for Pi's tool execution with a configurable security mode.** Automatically loaded - protects against: - **Partitioned command blocklist** - 41 CRITICAL commands (always blocked: system modification, privilege escalation, network attacks, shell escapes) + 25 EXTENDED commands (blocked in max mode: package management, process control, development tools) - **Mode-aware SSRF protection** - 22 ALWAYS_BLOCKED URL patterns (loopback, RFC1918 private ranges, cloud metadata endpoints) + 7 MAX_ONLY patterns (localhost by name, broadcast, link-local, current network) that are allowed in basic mode - **Security mode toggle** - switch between `basic`, `max`, and `off` modes at runtime; persisted to `~/.pi/agent/security.json` - **Path validation** - prevents filesystem escape and access to critical system directories; symlinks are dereferenced via `fs.realpathSync()` to block `/tmp/evil → /etc/passwd` bypasses - **Shell injection detection** - regex patterns for command chaining, substitution, and redirection - **Audit logging** - JSON-lines audit log at `~/.pi/agent/audit.log` with security mode recorded per entry (path exported as `AUDIT_LOG_PATH`) ```bash /security mode basic # Relaxed mode - CRITICAL commands blocked, localhost URLs allowed /security mode max # Full lockdown - all 66 commands blocked, strict SSRF /security mode off # Disable all security checks ``` **Default mode: `max`** - if `security.json` doesn't exist, the extension starts in max mode and creates it on first use. The current mode is displayed in the status bar (`SEC:BASIC`, `SEC:MAX`, or `SEC:OFF`). ### 🎭 SoulSpec (`soul.ts`) **Load and manage AI agent personas defined in SoulSpec format with progressive disclosure support and enhanced partial matching.** Automatically loaded - provides tools and commands for managing AI personas: - **Enhanced partial matching** - Flexible soul name matching with regex support for better tab autocomplete compatibility - **Soul loading** - Load personas from multiple locations with progressive disclosure (Level 1-3) - **Multiple locations** - Supports global (`~/.pi/agent/souls/`), project-local (`.pi/souls/`), and current directory (`./souls/`) soul storage - **Progressive disclosure** - Level 1 (basic info), Level 2 (core persona), Level 3 (extended behavior) - **Embodied agent support** - Hardware constraints, safety policies, sensors, and actuators - **Built-in tools** - `load_soul`, `list_souls`, `soul_info` for programmatic access with smart suggestions - **CLI commands** - `/souls` to list available souls, `/soul ` to use a soul with partial matching - **Smart error handling** - Helpful suggestions when no exact match is found - **Sample personas** - Includes `nova-helper` (coding assistant) and `robot-assistant` (physical robot) ```bash /souls # List all available souls /soul nova-helper # Use the Nova Helper persona (exact match) /soul dev # Load any soul containing 'dev' (partial matching) /soul /dev/ig # Load any soul with 'dev' (case-insensitive regex) /load_soul {"soul_name":"robot-assistant"} # Load robot assistant persona /soul_info robot-assistant # Get detailed information about a soul /soul --help # Show enhanced help with partial matching examples ``` **Partial matching features**: - **String matching** - `dev` matches `developer`, `assistant`, etc. - **Regex support** - `/dev/ig` for case-insensitive matching with flags - **Smart suggestions** - Shows potential matches when no exact match found - **Tab completion friendly** - Works seamlessly with shell tab autocomplete - **Single resolution** - Auto-resolves to one match, shows guidance for multiple **Soul locations** - The extension searches for souls in multiple directories: - `~/.pi/agent/souls/` - Global souls directory - `.pi/souls/` - Project-local souls directory - `./souls/` - Current directory souls **Sample souls included**: - **nova-helper** - Helpful coding assistant focused on clear explanations and practical solutions - **robot-assistant** - Physical robot assistant with voice interaction and manipulation capabilities ### 🔄 ReAct Fallback (`react-fallback.ts`) **Text-based tool calling bridge for models without native function calling support.** Automatically loaded - no commands needed. When a model lacks native tool calling: - Parses `Thought:`, `Action:`, `Action Input:` patterns from model output - **Multi-dialect support**: classic ReAct (`Action:`), Function (`Function:`), Tool (`Tool:`), Call (`Call:`) - each with dynamically-built regex patterns - Multiple regex strategies including parenthetical style and loose matching - Bridges text-based tool calls into Pi's native tool execution pipeline - Disabled by default; toggle via `/react-mode` with persistent config across restarts ### 💾 Long-Term Memory (`long-term-memory.ts`) **Persistent memory across sessions with automatic injection, AI-driven creation, and enhanced statistics.** ```bash /memory add - Add memory (with optional tags) /memory delete - Delete memory by ID or content /memory replace [comma-separated-tags] - Replace memory content by ID /memory list - List all memories /memory clear - Clear memories (preserves metadata) /memory clear-meta - Reset metadata /memory meta - Show metadata /memory backups - List available memory backups /memory stats - Show comprehensive memory statistics /memory-gate - Toggle memory creation gate /memory --help - Show help ``` ### Memory Management **Delete Operations:** - `/memory delete ` - Delete specific memory by ID - `/memory delete ` - Delete any memory containing the specified text **Replace Operations:** - `/memory replace ` - Replace memory content by ID - `/memory replace tag1,tag2` - Replace content and update tags ### Memory Statistics The `/memory stats` command provides detailed metrics: - Total memories count - Total content characters - Estimated tokens (rough calculation) - Average tokens per memory - Formatted context tokens - Memory gate status - Last compaction timestamp ### Enhanced Features - **User-Prompted Metadata**: Primary User, Environment, and Framework fields are now prompted on first run - **Backup System**: Automatic backup of pre-compacted memories to memory-backups directory - **Enhanced Error Handling**: Comprehensive debugging and error handling throughout memory operations - **Memory Injection Hooks**: Proper timing ensures memory is loaded and displayed before AI responses **Features:** - **Persistent Storage**: Memories survive across sessions and restarts - **Auto-Injection**: Memory automatically injected at session start, BEFORE the AI generates its first response - **AI-Driven Creation**: AI can request memories via `create_memory` tool - **Enhanced Metadata**: User-prompted Primary User, Environment, and Framework fields - **Memory Gate**: Confirm before creating memories (enabled by default) - **Tag Organization**: Organize memories with tags - **Token Management**: ~4k token window with auto-summarization - **Memory Statistics**: `/memory stats` command shows detailed metrics including total memories, content characters, estimated tokens, averages, and memory gate status - **Backup System**: Automatic backup of pre-compacted memories to memory-backups directory - **Enhanced Error Handling**: Comprehensive debugging and error handling throughout memory operations **Memory Injection Hooks:** - `pre_session_start` - Ensures metadata is complete - `session_start` - Displays memory context to user - `before_provider_request` - Prepends memory to the API request **Storage:** `.pi/agent/long-term-memory.json` ### 🔧 Hex Edit (`hex-edit.ts`) **A robust hex stream-based edit replacement that provides reliable, byte-level file editing with validation and transparency.** ```bash /hex-edit # Edit file using byte-level validation /hex-edit-show # Show file with line numbers and hex preview /hex-edit-validate # Validate that text exists in file /hex-edit-diff # Show byte-level diff between files ``` **Features:** - **Hex Stream Validation**: Uses byte-level comparison instead of text matching for maximum reliability - **LLM-callable Tools**: Tools that Pi can directly call for file operations - **Hash Verification**: Shows SHA-256 hashes before and after edits for verification - **Multiple Occurrence Handling**: Warns when multiple matches found and uses the first occurrence - **Detailed Output**: Displays file sizes, byte changes, and exact positions - **Error Handling**: Clear error messages for missing files and text not found - **Binary File Support**: Perfect for both text and binary file editing - **Typebox Validation**: All tools now use Typebox for robust parameter validation - **Streaming Support**: Progress updates during long operations - **Enhanced Hash Verification**: Both SHA-256 and simple hash for performance - **Better Context Display**: ±20 byte context in validation results - **Optimized Diff Output**: Shows first 50 lines for readability - **Proper Tool Labels**: Clear descriptions for better LLM understanding - **Automatic Recovery**: When the builtin `edit` tool fails, hex-edit automatically retries with byte-level validation (enabled by default) **Why Hex Edit?** The built-in `edit` tool uses text-based matching which can fail due to: - Whitespace differences - Encoding issues - Special characters - Partial matches Hex Edit solves this by: 1. Reading files as raw bytes 2. Finding exact byte sequences 3. Performing precise replacements 4. Validating changes via hash comparison When the built-in `edit` tool fails, hex-edit **automatically intercepts and retries** the operation with byte-level precision. No manual intervention needed! **Example:** ```bash /hex-edit src/index.ts "const old = 1" "const newVar = 2" /hex-edit-validate src/index.ts "some text" /hex-edit-show src/index.ts /hex-edit-diff file1.ts file2.ts ``` ### 🔄 Ollama Sync (`ollama-sync.ts`) **Auto-populate models.json with all available Ollama models - works with local and remote instances.** ```bash /ollama-sync # Sync from models.json URL (or localhost) /ollama-sync https://your-tunnel-url # Sync from a specific remote URL ``` - Queries Ollama `/api/tags` for available models (local or remote) - **Writes the actual Ollama URL back** into `models.json` so other extensions pick it up automatically - URL priority: CLI argument → existing `models.json` baseUrl → `OLLAMA_HOST` env → localhost - Preserves existing provider config (apiKey, compat settings) - Defaults to `openai-completions` API mode (correct for Ollama's `/v1/chat/completions` endpoint) - Sorts models by size (smallest first) - Auto-detects reasoning-capable models (deepseek-r1, qwq, qwen3, o1, o3, think, reason) - Merges with existing per-model settings - Per-model metadata in sync report (parameter size, quantization level, model family) - Registered as both `/ollama-sync` slash command and `ollama_sync` tool ### 🔗 OpenRouter Sync (`openrouter-sync.ts`) **Add OpenRouter models to models.json from URLs or bare model IDs.** ```bash /or-sync [url-or-id ...] # Alias /openrouter-sync [url-or-id ...] ``` - Accepts full OpenRouter URLs (`https://openrouter.ai/model/name:free`) or bare IDs (`model/name:free`) - Multiple models in one command - Strips query parameters and fragments from URLs before extracting model name - Creates `openrouter` provider in models.json if missing (inherits baseUrl/api from built-in provider registry) - Appends models, never removes existing entries - Reorders providers so openrouter sits above ollama - Registered as both `/openrouter-sync` slash command (alias `/or-sync`) and `openrouter_sync` tool ### 📁 Workspace (`workspace.ts`) **Manage, archive, and restore workspaces with session state.** ```bash /workspace — Show workspace management help /workspace save — Save current workspace state /workspace load — Load a saved workspace /workspace list — List all saved workspaces /workspace delete — Delete a saved workspace /workspace current — Show current workspace state ``` **Features:** - Saves session name, skills, extensions, configs, and soul state - Automatically detects git repositories in the workspace - Archives content files when no git repos are present - Tracks extension sources (local, git, or package-based) - Skips large/binary files and `!dirs` reference folders - Workspaces stored in `~/.pi/agent/workspaces/` as `.ws.json` files --- ### 📊 System Monitor (`status.ts`) **Adds composable named status items to the framework footer using `ctx.ui.setStatus()`. Each metric gets its own slot so it coexists cleanly with other extensions' status items.** CPU/RAM/Swap are only shown when using a local Ollama provider (not for cloud/remote). For cloud providers, system metrics are omitted. Model name, session tokens, and context usage are shown by the framework - not duplicated here. All labels use dimmed coloring; all values use green highlighting. **Status slots (updated every 5s, 1s for active tool):** - **CtxMax + RespMax** - combined slot showing native model context window and max response/completion tokens (e.g., `CtxMax:33k RespMax:16.4k`) - **Resp** - agent loop duration via `agent_start`/`agent_end` events - **CPU%** - per-core delta via `os.cpus()` (local Ollama only) - **RAM** - used/total via `os.totalmem()` / `os.freemem()` (local Ollama only) - **Swap** - used/total from `/proc/meminfo` (shown only when swap is active, local only) - **Generation params** - temperature, top_p, top_k, num_predict, context size, reasoning_effort (dimmed) - **SEC** - security mode indicator (`SEC:BASIC` or `SEC:MAX`) + session-scoped blocked count + 3s flash on blocked tools (resets on shutdown) - **Active tool** - live elapsed timer with `>` indicator while a tool is running - **Prompt** - system prompt size as `chars chr tokens tok` displayed on agent start - **Pi version** - `pi:0.66.1` fetched once at `session_start` (dim label + green value, always last slot) All slots are cleared on session shutdown. Metrics that the framework already provides (model name, session tokens, context usage, thinking level) are intentionally omitted to avoid duplication. --- ## Themes ### 🟢 Matrix (`matrix.json`) A Matrix movie-inspired theme with neon green on pure black. Designed for terminal aesthetics and extended coding sessions. ``` /theme matrix ``` **Color palette:** | Token | Color | Usage | |-------|-------|-------| | `green` | `#39ff14` | Primary text - neon green | | `brightGreen` | `#7fff00` | Accents, headings, inline code, highlights | | `phosphor` | `#66ff33` | Links, tool titles, code block text, secondary text | | `glowGreen` | `#00ff41` | Thinking text, quotes | | `fadeGreen` | `#00cc33` | Muted text, borders | | `hotGreen` | `#b2ff59` | Numbers, emphasis | | `yellow` | `#eeff00` | Status bar active tool timer | | Background | `#000000` | Pure black base | --- ## Quick Start ```bash # 1. Install the package pi install git:github.com/VTSTech/pi-coding-agent # 2. Restart Pi pi -c # 3. Sync your Ollama models into Pi (or use a cloud provider) /ollama-sync # Local Ollama /ollama-sync https://your-tunnel-url # Remote Ollama (e.g., Cloudflare Tunnel) # 4. Reload Pi to pick up model changes /reload # 5. Run diagnostics to verify everything /diag # 6. Benchmark your models /model-test --all # 7. (Optional) Use long-term memory for persistent sessions /memory list # View saved memories /memory add "Remember to use TypeScript" # Add a memory ``` ### Remote Ollama Setup If Ollama is running on a different machine, expose it via a tunnel and point Pi at it: ```bash # On the Ollama machine - create a tunnel (example with cloudflared) cloudflared tunnel --url http://localhost:11434 # In Pi - sync models from the tunnel URL /ollama-sync https://your-tunnel-url.trycloudflare.com ``` The URL gets saved to `models.json` and all extensions use it automatically. No need to set `OLLAMA_HOST` or pass the URL again. ### Cloud Provider Setup Pi handles cloud providers natively - just set your API key in the environment and select a model: ```bash export OPENROUTER_API_KEY="sk-or-..." # In Pi - select a cloud model /model openrouter/openai/gpt-oss-120b:free # Test it /model-test ``` ### Recommended models.json ```json { "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }, "models": [] } } } ``` > Use `/ollama-sync` to auto-populate the models array and set the correct `baseUrl` from your Ollama instance. ### Recommended settings.json Optimized for CPU-only environments with limited RAM: ```json { "defaultProvider": "ollama", "defaultModel": "granite4:350m", "defaultThinkingLevel": "off", "theme": "matrix", "compaction": { "enabled": true, "reserveTokens": 2048, "keepRecentTokens": 8000 } } ``` --- ## Supported API Modes Pi supports multiple API backends via the `api` field in `models.json`. For Ollama, use **`openai-completions`** which maps to Ollama's native `/v1/chat/completions` endpoint. Other available modes: | API Mode | Use Case | |----------|----------| | `openai-completions` | Ollama, OpenAI-compatible `/v1/chat/completions` | | `openai-responses` | OpenAI Responses API (`/v1/responses`) | | `anthropic-messages` | Anthropic native API | | `google-generative-ai` | Gemini API | | `google-vertex` | Google Vertex AI | | `mistral-conversations` | Mistral API | | `bedrock-converse-stream` | Amazon Bedrock | See [Pi's AI package docs](https://github.com/badlogic/pi-mono/tree/main/packages/ai#apis-models-and-providers) for the full list. --- ## Google Colab Setup These extensions are optimized for running Pi on **Google Colab with CPU-only and 12GB RAM**. Here's the recommended Ollama launch configuration: ```python import subprocess, os # Install Ollama subprocess.run(["curl", "-fsSL", "https://ollama.com/install.sh"], check=True) # Environment tuning for CPU-only 12GB os.environ["OLLAMA_HOST"] = "0.0.0.0:11434" os.environ["CONTEXT_LENGTH"] = "4096" # Reduce from 262k default os.environ["MAX_LOADED_MODELS"] = "1" # Only one model in memory os.environ["KEEP_ALIVE"] = "2m" # Unload after 2min idle os.environ["KV_CACHE_TYPE"] = "f16" # Use f16 for KV cache os.environ["OLLAMA_MODELS"] = "/tmp/ollama" # Store in tmpfs (RAM disk) os.environ["BATCH_SIZE"] = "512" # Smaller batches for CPU os.environ["NO_CUDA"] = "1" # Force CPU mode # Start Ollama subprocess.Popen(["ollama", "serve"]) ``` ### Recommended Models (12GB RAM) | Model | Params | Size | Reasoning | Tools | Best For | |-------|--------|------|-----------|-------|----------| | `granite4:350m` | 352M | 676 MB | ❌ | ✅ | Fast tasks, tool calling | | `qwen3:0.6b` | 752M | 498 MB | ❌ | ✅ | Small footprint, native tools | | `qwen3.5:0.8b` | ~800M | 1.0 GB | ❌ | ✅ | Daily driver | | `qwen2.5-coder:1.5b` | 1.5B | 940 MB | ❌ | ✅ | Code tasks | | `llama3.2:1b` | 1.2B | 1.2 GB | ❌ | ✅ | General use | | `qwen3.5:2b` | 2.3B | 2.7 GB | ✅ | ✅ | Best quality (fits 12GB) | --- ## Tested Models See [TESTS.md](https://github.com/VTSTech/pi-coding-agent/blob/HEAD/TESTS.md) for full benchmark results across all tested Ollama and cloud provider models. --- ## File Structure ``` pi-coding-agent/ ├── extensions/ │ ├── api.ts # API mode switcher - modes, URLs, thinking, compat flags │ ├── diag.ts # System diagnostic suite │ ├── model-test.ts # Model benchmark - Ollama & cloud providers │ ├── ollama-sync.ts # Ollama ↔ models.json sync │ ├── openrouter-sync.ts # OpenRouter → models.json sync │ ├── react-fallback.ts # ReAct fallback for non-native tool models │ ├── security.ts # Command/path/SSRF protection │ ├── soul.ts # SoulSpec persona management │ ├── status.ts # System resource monitor & status bar │ └── workspace.ts # Workspace management & state persistence ├── shared/ │ ├── debug.ts # Conditional debug logging │ ├── format.ts # Shared formatting utilities │ ├── model-test-utils.ts # Shared test utilities, config, history │ ├── ollama.ts # Ollama API helpers, provider detection, mutex, retry │ ├── react-parser.ts # Multi-dialect ReAct text parser │ ├── security.ts # Security validation, SSRF, DNS rebinding, audit log │ └── types.ts # TypeScript types & error classes ├── themes/ │ └── matrix.json # Matrix movie theme ├── individual-packages/ # Source for individual npm packages │ ├── pi-shared/ # Shared utilities (bundled into extensions) │ ├── pi-api/ # API mode switcher │ ├── pi-diag/ # System diagnostics │ ├── pi-model-test/ # Model benchmarking │ ├── pi-ollama-sync/ # Ollama synchronization │ ├── pi-openrouter-sync/ # OpenRouter synchronization │ ├── pi-react-fallback/ # ReAct fallback │ ├── pi-security/ # Security extensions │ ├── pi-soul/ # SoulSpec personas │ ├── pi-status/ # System monitoring │ └── pi-workspace/ # Workspace management ├── dist/ # Built npm packages (published to npmjs.com) ├── scripts/ │ ├── build-tgz.sh # Build all individual .tgz packages │ ├── bump-version.sh # Linux/macOS version bump script │ └── bump-version.ps1 # Windows PowerShell version bump script ├── CHANGELOG.md # Version history ├── TESTS.md # Model benchmark results ├── VERSION # Single source of truth for version ├── package.json # Pi package manifest ├── README.md └── LICENSE ``` --- ## About
**Written by [VTSTech](https://github.com/VTSTech)** [🌐 www.vts-tech.org](https://www.vts-tech.org) • [🐙 GitHub](https://github.com/VTSTech) • [📧 veritas@vts-tech.org](mailto:veritas@vts-tech.org)

Optimizing AI agent development for resource-constrained environments.