My Pi Coding Agent Stack

The rise of LLM-driven (Large Language Models) coding assistants has profoundly altered how we design, prototype, and maintain software. Yet, most solutions on the market (IDE extensions, proprietary closed-sandbox apps, or naive CLI tools) impose major trade-offs: ephemeral contexts that vanish when a session ends, blocking sequential execution, an inability to interact asynchronously with external systems, and zero guardrails over executed shell commands.

To overcome these constraints, I built a tailored ecosystem centered around Pi Coding Agent (@earendil-works/pi-coding-agent), a modular and extensible coding agent written in TypeScript.

This stack goes far beyond running simple bash commands or editing text files. It embeds a dual-model SQLite persistent memory engine, a subagent orchestrator (pi-subagents) running up to 10 background workers with Git worktree isolation and specialized profiles (Explore, Plan), a bidirectional real-time Discord bridge for remote mobile orchestration, an advanced MCP gateway tied into my Zero Trust infrastructure, proactive system command safety, and an Antigravity provider harnessing state-of-the-art reasoning models (thinking models) and image generation.

Here is the complete technical deep dive into this architecture.

Architecture Overview

The overall architecture of my Pi stack is structured in interconnected layers, enforcing a strict separation of concerns between orchestration runtime, domain extensions, storage engines, and external interfaces:

flowchart TB
    subgraph UI["User Interfaces & Remote Control"]
        TUI["Pi TUI (Interactive Terminal)"]
        Discord["Discord Mobile / Desktop<br>Interactive Buttons & Webhooks"]
    end

    subgraph Runtime["Pi Coding Agent Core (TypeScript / Node.js)"]
        Core["Pi Orchestrator & State Machine"]
        ExtLoader["Extension & Package Loader"]
        ToolManager["Tool Registry & Guardrails"]
    end

    subgraph LLMProviders["LLM & Provider Layer"]
        Antigravity["pi-antigravity (OAuth Google Cloud Code)<br>Gemini 3.7 Flash Thinking / Pro"]
        Quotas["pi-quotas (Rate Limits & Token Trackers)"]
    end

    subgraph Parallelism["Parallel Execution & Multiplexing"]
        Subagents["pi-subagents (Pi 1.4.0 & RPC pi.events)<br>Nested Delegation, Explore, Plan & Worktree"]
        PTYManager["terminal manager (Persistent PTY)<br>Background Sessions & Regex Monitor"]
    end

    subgraph MemoryLayer["Long-Term Persistent Memory"]
        SQLiteDB[("observational-memory.sqlite<br>Branch Ledger & Compaction")]
        Observer["Observer Model (Headless Pi)<br>Atomic Observation Extraction"]
        Consolidator["Consolidator Model<br>Thematic Long-Term Consolidation"]
    end

    subgraph SecurityExt["Security & Local Tooling"]
        BashGuard["bash-guard (L7 Interception & Confirmation)"]
        MoveTool["move-tool (AST Relocation & Rollback)"]
        TodoTool["pi-todotools (Phased State Machine)"]
        SearchTools["pi-web-search & Gemini URL Context"]
    end

    subgraph MCPLayer["Native MCP Gateway (mcp.json)"]
        MCPEngine["Native MCP Client & +codemode Tool"]
        CFAPI["Cloudflare API (deferred) & Browser (direct)"]
        Context7["Context7 (Real-time Docs)"]
        GrepApp["Grep.app (GitHub Code Search)"]
        GitHubMCP["GitHub Copilot MCP (Dynamic Token)"]
        LugoMCP["Lugo (Lua 5.4 LSP & MCP)"]
    end

    UI <--> Runtime
    Runtime --> LLMProviders
    Runtime --> Parallelism
    Runtime --> MemoryLayer
    Runtime --> SecurityExt
    Runtime --> MCPLayer
    Discord <-->|"pi-bridge (HTTPS / Webhooks)"| Runtime

1. The Model Engine: pi-antigravity & pi-quotas

The foundation of any coding agent lies in the quality of its language models and the resilience of its API transport layer.

pi-antigravity: Google Cloud Code Integration

Rather than relying on a single provider, I leverage multiple backends depending on the task. pi-antigravity implements direct OAuth authentication with Google Antigravity / Cloud Code internal services, while my daily local configuration currently uses OpenAI Codex as its default provider. The runtime has been upgraded to Pi 1.4.0, managing dependencies and subagents centrally. Private preferences remain decoupled from the shareable repository configuration.

{
  "lastChangelogVersion": "1.4.0",
  "theme": "dark",
  "defaultProvider": "openai-codex",
  "defaultModel": "gpt-6-luna",
  "enableInstallTelemetry": false,
  "enableAnalytics": false,
  "packages": [
    "git:github.com/FRFlo/pi-web-search",
    "git:github.com/code-yeongyu/pi-apply-patch",
    "git:github.com/FRFlo/pi-todotools",
    "git:github.com/FRFlo/pi-quotas",
    "npm:pi-antigravity",
    "npm:pi-lsp",
    "npm:@tintinweb/pi-subagents"
  ],
  "observational-memory": {
    "backend": "sqlite",
    "models": {
      "observer": {
        "provider": "antigravity",
        "id": "gemini-3.7-flash"
      },
      "consolidator": {
        "provider": "antigravity",
        "id": "gemini-3.7-flash"
      }
    }
  },
  "terminal": {
    "notify": "next-turn"
  },
  "hideThinkingBlock": true,
  "defaultTools": ["+codemode"]
}

This integration delivers several crucial benefits:

1. Native Access to Thinking Models: Transparent access to Gemini thinking models in the Antigravity catalog with fine-grained reflection levels (off, low, medium, high, max).
2. Automated Selected Model Persistence: Powered by the model_select event hook in preferences-loader.ts, runtime model and provider selections are saved dynamically into preferences.json, guaranteeing cross-session continuity without manual configuration edits.
3. Built-in Image Generation (generate_image): Ability for the agent to design UI mockups, visual assets, or architecture diagrams directly using Imagen / Gemini without breaking the development loop.
4. Automated OAuth Token Lifecycle: Seamless credential renewal without requiring manual API keys scattered across shell environment variables.

pi-quotas: Real-Time Consumption & Limit Tracking

Custom-built for my setup, pi-quotas hooks into Pi’s lifecycle events to inspect response headers, token counters, and remaining rate limits per model in real time. It enables predictive throttling to avoid hitting walls during intensive multi-file refactoring runs.

2. Long-Term Persistent Memory: observational-memory

One of the most persistent hurdles with AI coding agents is context amnesia: as discussions grow, the context window saturates, triggering either destructive truncation or crude summarization that drops subtle architectural choices.

To address this deterministically, my stack integrates Observational Memory, a hierarchical memory architecture backed by SQLite.

flowchart LR
    A["Conversation Chunks<br/><i>Token-based windows</i>"] --> B["Parallel Observers<br/><i>Headless pi instances</i>"]
    B --> C["Atomic Observations<br/><i>{timestamp, content, context}</i>"]
    C --> D["SQLite Master Ledger<br/><i>observational-memory.sqlite</i>"]
    D --> E["Deterministic Compaction<br/><i>Zero-LLM call (no hallucinations)</i>"]
    D --> F["Consolidator Model<br/><i>Dedicated gemini-3.7-flash</i>"]
    F --> G["Durable SQLite Storage<br/><i>Thematic Archives & Session Scopes</i>"]

How the Dual-Model (Observer / Consolidator) Architecture Works

1. The Observer (Asynchronous Observer): In the background, lightweight sub-processes analyze recent dialogue chunks to pull out atomic observations (facts, user preferences, design decisions, bug fixes). Their internal worker sessions are automatically hidden from the conversation tree to preserve a clean main transcript.
2. The SQLite Master Ledger: Every observation and snapshot is committed to a unified local SQLite database (observational-memory.sqlite). This table structure maps directly to Pi’s session tree (/tree), guaranteeing that if a session branches or rolls back, memory mirrors the active branch.
3. Deterministic Compaction: Unlike traditional setups where an LLM rewrites the prompt (risking hallucination or data loss), Pi’s compaction compiles validated observations directly into the system context.
4. The Consolidator and Durable SQLite Storage: Periodically, the consolidator model consolidates older observations directly within the local SQLite database (observational-memory.sqlite). Intermediate Markdown files on disk are eliminated: thematic archives and session history are stored durably within SQLite, ensuring clean isolation between projects and sessions while enabling instant memory scope cloning on session forks. The .memory/ directory is now solely an ephemeral sandbox for worker processes.

3. Parallel Subagent Orchestration: pi-subagents

Complex engineering tasks frequently demand multiple parallel workstreams: exploring an unfamiliar codebase, auditing build logs, running non-regression test suites, and architecting new features.

The stack has migrated to pi-subagents (the @tintinweb/pi-subagents@0.22.0 package, fork FRFlo/pi-subagents), running on Pi 1.4.0 and replacing the legacy interactive-subagents submodule. Inspired by Claude Code, it provides full-fledged asynchronous subagent orchestration configured declaratively through subagents.json.

╭─ Subagents ────────────────────────── 3 running ─╮
│ 00:12  Explore   active · grep 2m (worktree)     │
│ 00:18  Plan      active · codex 4m               │
│ 00:25  Reviewer  waiting (RPC delegate)          │
╰──────────────────────────────────────────────────╯

Declarative Orchestration (subagents.json)

The extension is centrally configured for high concurrency, isolation, and developer visibility:

• High Concurrency & Background Workers: maxConcurrent: 10 with backgroundByDefault: true. The primary agent is never stalled while a subagent inspects code or runs tests.
• Git Worktree Isolation (worktreeIsolation: true): Subagents mutating or compiling code operate in independent Git worktrees, eliminating race conditions or file lock contention against the main working directory.
• TUI Observability (fleetView: true, widgetMode: "all"): A real-time panoramic fleet overview and interactive terminal widget summarizing the active state, duration, and underlying model of every running worker.
• Nesting & Smart Merging: Supports nested subagents up to depth 2 (maxSubagentDepth: 2) with intelligent context reconciliation (defaultJoinMode: "smart").

Specialized Global Agent Profiles (agents/)

Instead of instantiating bloated, generic workers with full toolsets, the stack defines task-specific agent profiles under agents/ using strict prompt replacement (prompt_mode: replace) or appending (prompt_mode: append), scoped tool allowlists, and explicit authorization for nested delegation (allowed_subagents: all):

1. Explore (agents/Explore.md): A high-speed, read-only codebase navigation and symbol search specialist (tools: read, bash, grep, find, ls). The prompt strictly forbids file modifications, writes, or temporary directory escapes, while Bash is restricted to read-only diagnostics (git status, git diff, cat, etc.). Powered by antigravity/gemini-3.8-flash for ultra-fast, cost-effective exploration, with sub-delegation authorized (allowed_subagents: all).
2. Plan (agents/Plan.md): A software architect agent producing structured implementation plans without modifying code (tools: read, bash, grep, find, ls). Powered by openai-codex/gpt-6.1-sol, it systematically explores context, assesses trade-offs, identifies sequencing dependencies, flags critical implementation files, and authorizes sub-delegation (allowed_subagents: all).
3. general-purpose (agents/general-purpose.md): A comprehensive general-purpose agent profile (tools: all, allowed_subagents: all, prompt_mode: append) capable of managing complete workflows while cascading independent subtasks.
4. supervisor-planner (agents/supervisor-planner.md): A zero-tool agent (tools: none) converting user requests into structured Todo items accompanied by private verification criteria.
5. supervisor-reviewer (agents/supervisor-reviewer.md) : A read-only verification agent (tools: read, grep, find, ls) independently verifying completed Todo checkpoints against private acceptance criteria and original request intent.

Orchestration Guidelines & Independent Critique (APPEND_SYSTEM.md)

To guide agent autonomy and preserve review rigor, global directives are appended to the system prompt:

• Systematic Exploration & Decomposition: For broad or ambiguous requests, the agent delegates decomposition and exploration to background subagents. Implementation work is likewise sub-delegated when it can be partitioned into independent, non-conflicting tasks.
• Unbiased Independent Review: Whenever a task involves challenging, auditing, or reviewing existing work, the critique is strictly assigned to a fresh-context subagent. It receives the work and review criteria, but intentionally omits the primary agent’s conclusions or private reasoning to guarantee an impartial assessment.
• Proportionate Planning & Targeted Questions: Multi-step tasks must be planned before action. When discovering material ambiguities that affect the implementation path, the question tool clarifies the requirement without halting the turn for minor, non-blocking details.

Event-Driven RPC Delegation (pi.events)

The supervisor extension (extensions/supervisor/index.ts) no longer imports private subagent classes. It interfaces with pi-subagents entirely over Pi’s event-driven RPC channels:

• RPC Lifecycle: Spawning subagents (subagents:rpc:spawn), listening for completions or errors (subagents:completed, subagents:failed), and consuming results (subagents:rpc:consume, subagents:rpc:stop).
• Hidden Technical Sessions (persistSession: false): Planner and reviewer subagent sessions are marked non-persistent to prevent transient audit turns from cluttering the primary session history.
• Instruction Boundary: The reviewer’s instructions strictly constrain inspection to the active repository, treating worker claims as untrusted until validated by independent evidence.

4. Remote Supervision & Real-Time Discord Mobile Bridge

To stay in full control during long autonomous tasks while away from my workstation, the stack incorporates a real-time bidirectional Discord bridge.

sequenceDiagram
    participant Pi as Pi Coding Agent
    participant Bridge as pi-bridge (API)
    participant Discord as Discord Client (Mobile/Web)

    Pi->>Bridge: POST /ask (Question + Options + Context)
    Bridge->>Discord: Embed Message + ActionRow Buttons
    Note over Discord: User taps an option<br/>or types a custom reply
    Discord->>Bridge: Webhook Interaction (Button Click / Modal)
    Bridge-->>Pi: HTTP Response Resolved (Chosen Option / Text)
    Pi->>Pi: Resumes Execution Flow Immediately

The ask-user-question Tool & Reactive TUI

Whenever an architectural fork or permission check arises, ask_user_question adapts to the current environment:

1. Interactive TUI Mode: In the terminal, it renders an ANSI keyboard-navigable list (arrow keys, spacebar for multi-select, custom text prompt).
2. Instant Discord Sync: Concurrently, the payload is forwarded to the pi-bridge service, rendering interactive buttons in a designated Discord channel. Whether I click a button on my phone or select an option in my terminal, the execution loop unblocks immediately.
3. Headless RPC Mode (hermes-rpc): When orchestrated externally by Hermes Agent via its JSONL RPC interface, dialogs fallback to serializable primitives (hermesSelect, hermesInput), enabling programmatic selection without requiring an active terminal UI.
4. Persistent Questions & Proactive Reports: ask_user_question automatically persists and restores pending questions across reloads or session interruptions, preventing stalled execution loops. A question can remain open until answered via either the TUI, Discord, or the RPC bridge, while send_discord_message delivers build completions, regression alerts, and deployment summaries formatted in rich Markdown.

5. Persistent PTY Terminal & Proactive Security: terminal & bash-guard

Letting an autonomous agent run arbitrary shell commands on a development machine carries inherent risks: accidental destructive operations, orphaned background processes, and unconstrained resource consumption.

Persistent PTY Management & the monitor Pattern

The terminal extension equips Pi with full pseudo-terminal session management:

• Dynamic Terminal Context Injection: The execution runtime dynamically injects current terminal state (active working directory, recent commands, execution exit codes) into the prompt without needlessly flooding the context window.
• Background Processes: Long-running dev servers, docker compose services, or heavy builds run without blocking the REPL.
• Event-Driven Subscriptions (monitor): Instead of actively polling output logs, the agent subscribes to regex patterns (e.g. READY, Compiled successfully, ERROR), waking up only when the pattern matches or the process exits.
• Interactive REPL Steering: Real-time keystroke and signal injection (ctrl+c, bash_input, bash_resize).

bash-guard: L7 Proactive Security Interceptor

To guard against costly typos or unintended commands, every shell execution passes through bash-guard:

• Syntax Inspection: Detects high-risk patterns (rm -rf /, raw disk writes, unvetted privilege escalations).
• Adaptive Confirmation Floor: Whenever a command crosses safety thresholds, it pauses execution and demands explicit user confirmation (via TUI, Discord, or headless RPC selection).

6. The Native MCP Gateway (mcp.json) & +codemode Tool

The MCP (Model Context Protocol) standard lets the agent interact directly with external platforms. In earlier versions of the stack, this connection relied on an intermediary adapter package (pi-mcp-adapter). The architecture now builds directly on Pi’s native MCP client, declared centrally in mcp.json and coupled with the +codemode programmatic execution tool enabled in settings.json.

This migration to the native engine unlocks several critical architectural enhancements:

• Fine-Grained Exposure Control (exposure): Dense servers such as cloudflare-api (which expose dozens of distinct endpoints) are configured with exposure: "deferred". Their tool definitions are not dumped en masse into the initial system prompt to burn context tokens, but are resolved dynamically on demand via tool search. Conversely, essential web extraction tools (cloudflare-browser) are exposed immediately (exposure: "direct").
• Secure Dynamic Header Resolution: Ephemeral access tokens (such as for GitHub Copilot MCP) are resolved on the fly via shell command interpolation (!echo Bearer $(gh auth token)), preventing static secrets from lingering on disk.
• Zero-Allocation Local Tooling: The local Lugo MCP server (~/.pi/agent/bin/lugo-mcp.exe), compiled as a standalone Go binary, runs directly against the workspace tree with sub-millisecond AST diagnostics.

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
      }
    },
    "grep_app": {
      "url": "https://mcp.grep.app"
    },
    "cloudflare-api": {
      "url": "https://mcp.cloudflare.com/mcp",
      "exposure": "deferred"
    },
    "cloudflare-browser": {
      "url": "https://browser.mcp.cloudflare.com/mcp",
      "exposure": "direct"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "!echo Bearer $(gh auth token)"
      }
    },
    "svelte": {
      "command": "bunx",
      "args": ["-y", "@sveltejs/mcp"]
    },
    "gitnexus": {
      "command": "bunx",
      "args": ["-y", "gitnexus", "mcp"]
    },
    "lugo": {
      "command": "~/.pi/agent/bin/lugo-mcp.exe",
      "args": ["."],
      "cwd": "."
    },
    "chrome-devtools": {
      "command": "bunx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "enabled": false
    }
  }
}

1. cloudflare-browser: Visual Web Access & Headless Scraping (Top Priority)

This is one of the most critical MCPs in the entire stack. Unlike a simple curl or text fetch that falls flat on dynamic JavaScript applications, cloudflare-browser drives a remote Chromium instance hosted on Cloudflare’s Edge:

• Full SPA & Dynamic Page Rendering: Instant conversion of modern web apps into clean Markdown (get_url_markdown) or raw DOM trees (get_url_html_content).
• Structured JSON Extraction (get_url_json): Schema-driven extraction powered by AI directly from web pages using natural language prompts.
• Asynchronous Web Crawls (start_crawl / get_crawl_result): Recursive background crawls across entire documentation hubs.

2. context7: Up-to-Date Official Framework Docs

Pre-trained LLM weights naturally freeze at their training cutoff and frequently hallucinate newer APIs or major framework redesigns. context7 bridges this gap:

• Accurate Library Resolution (context7_resolve-library-id): Maps package identifiers to exact library versions.
• Concept-Scoped Docs Querying (context7_query-docs): Pulls official, verified code samples and current documentation chunks directly into context.

3. grep_app: Searching Real-World Code Across GitHub

Official guides often stop at simplified “hello world” demos. grep_app gives the agent direct visibility into how production codebases use libraries in the wild:

• Literal Pattern & Regular Expression Searches (grep_app_searchGitHub) indexing over one million public repositories.
• Pattern Verification: Validates function signatures, real-world error handling patterns, advanced TypeScript configurations, and multi-library interop.

4. Infrastructure & Ecosystem MCPs

• cloudflare-api: Deferred search across OpenAPI specs and direct execution for orchestrating Workers, D1 databases, KV namespaces, R2 buckets, DNS, and WAF rules.
• lugo: Native MCP server for Lua 5.4 (~/.pi/agent/bin/lugo-mcp.exe) built upon Flo’s custom zero-allocation engine (FRFlo/lugo), delivering deep syntax inspection and AST capabilities for Lua and FiveM scripts.
• chrome-devtools: Chrome DevTools MCP integration (chrome-devtools-mcp@latest) for inspecting web pages, live DOM querying, and frontend testing.
• github: Dedicated connector for GitHub Copilot endpoints with dynamic on-the-fly token resolution (!echo Bearer $(gh auth token)).
• Privacy & Telemetry Stripping: All external analytics and telemetry reporting have been strictly disabled (enableInstallTelemetry: false, enableAnalytics: false), and @posthog/pi has been removed to guarantee absolute confidentiality across all coding and reasoning sessions.

Programmatic Tool Execution: +codemode

To maximize efficiency and eliminate token churn during multi-step interactions, the stack natively enables +codemode in defaultTools. Rather than ping-ponging through multiple conversational turns to aggregate or filter tool results, the agent authors and executes sandboxed TypeScript. This code invokes needed local MCP tools directly, iterates or transforms the data, and returns only the concise synthesized result to the primary model context.

7. Specialized Tooling: Refactoring, Tasks & Context

Alongside the core extensions, the stack incorporates several purpose-built utilities:

8. Specialized Skill System

Skills deliver modular sets of domain-specific guidelines and checklists loaded dynamically based on project requirements:

• Cloudflare Architecture: cloudflare, wrangler, durable-objects, agents-sdk, sandbox-sdk, cloudflare-one.
• Design Engineering & UI/UX: impeccable (visual hierarchy, accessibility, typographic scale), make-interfaces-feel-better (physics, transitions, micro-interactions), responsive-craft.
• Code Quality Guidelines: karpathy-guidelines (averting LLM overcomplication, surgical changes, verifiable test gates).
• Performance & Debugging: web-perf (Core Web Vitals), web-debug (live Playwright DOM & network tracing).

Daily Workflow & Engineering Impact

Integrating these components into a single coherent system transforms daily development:

1. Mission Initialization: Starting a Pi session in a codebase prompts pi-nested-agents-md to load project rules, while todo lays out a structured roadmap.
2. Exploration & Concurrency: While the main agent tackles core logic, a background Explore subagent operates in an isolated Git worktree under a read-only allowlist to investigate real-world usage on grep_app or query context7 for docs.
3. Safety & Mobile Steering: If a high-stakes decision or sensitive shell command is reached while I am away, an interactive notification pings Discord. A single tap confirms the operation and the agent proceeds.
4. Cognitive Persistence: Through observational-memory, key learnings (resolved edge cases, library quirks, API conventions) are committed to SQLite, continuously refining future sessions.

Conclusion

The true leverage of an AI coding agent does not hinge solely on the parameter count of the foundational LLM, but on the depth, responsiveness, and safety of its execution environment.

By unifying deterministic persistent memory, asynchronous concurrency, a Zero Trust MCP gateway, multi-channel interactivity (TUI + Discord), and proactive guardrails, this stack elevates Pi into a genuine autonomous engineering partner built for production software development.