Pi Coding Agent Review: Minimal, Hackable AI Coding CLI

Introduction

The AI coding tooling space has saturated with heavy IDE extensions and monolithic agents that abstract away every layer of the generation pipeline. Pi takes a different route. It is a terminal-native CLI built for developers who want explicit control over context assembly, prompt routing, and output validation. I integrated Pi into our internal microservice scaffolding and CI workflows over the past three weeks. This review breaks down the architecture, plugin system, and where the tool actually delivers value in production environments.

Pi does not try to replace your editor. It operates as a surgical pipeline stage: you pipe in a target, it assembles context, routes the request, and returns a unified diff. The design philosophy leans heavily into Unix principles. Every component is scriptable, state is explicit, and the execution loop is fully observable.

Why This Matters

Modern AI IDE plugins often treat the LLM as a black box. You get suggestions, but you lose visibility into what files were injected into the context window, how tokens were allocated, and whether the output was validated against your project’s type system. When a refactor silently breaks a critical path, debugging that black box is expensive.

Pi solves this by exposing every stage of the generation loop as a composable CLI step. It treats LLM interaction like a deterministic pipeline: context resolution, hook execution, prompt assembly, model dispatch, and diff patching are all separate, testable stages. This matters because it gives engineering teams auditability, token efficiency, and the ability to enforce architectural guardrails before code ever reaches the model or your repository.

How It Works

The execution pipeline follows a strict linear flow with intercept points for plugins. When you run pi generate --target src/auth/, the CLI initiates a context resolution pass. It scans the target directory, applies your .piignore rules, and builds a lightweight context manifest. The manifest gets passed through a pre-prompt hook chain, where registered plugins can modify, filter, or reject the payload. Once validated, the prompt assembler formats the context into a structured payload and streams it to your configured LLM endpoint. The response is parsed into a unified diff, routed through post-prompt validation hooks, and finally presented as a patch or applied directly.

flowchart TD
  A[CLI Input] --> B[Context Resolver]
  B --> C[Pre-Prompt Hook Chain]
  C --> D[Prompt Assembler]
  D --> E[LLM Gateway]
  E --> F[Diff Patcher]
  F --> G[Post-Prompt Hook Chain]
  G --> H[Output / Apply]
  B -->|File Tree + AST Metadata| C
  D -->|Structured JSON Payload| E
  F -->|Unified Diff Stream| G
  C -->|Modified Context| D
  G -->|Validated Patch| H

The Context Resolver uses a fast filesystem walker paired with a lightweight AST parser to extract import graphs and symbol boundaries. This prevents the common problem of dumping entire monorepos into the context window. The LLM Gateway handles backpressure natively: if the provider throttles or the stream stalls, Pi buffers chunks and retries with exponential backoff. The Diff Patcher does not write to disk until the post-prompt chain confirms the patch passes your configured validation rules.

Core Concepts

Pi’s architecture rests on four foundational components:

1. Context Manifest: A structured JSON representation of the files, line ranges, and AST metadata being sent to the model. It includes relevance scores, dependency edges, and explicit exclusion flags.
2. Lifecycle Hooks: Async interceptors that run at defined stages (onBeforeAssemble, onAfterGenerate, onBeforeApply). Hooks can mutate the payload, reject execution, or inject custom validation logic.
3. Token Budgeting: A runtime tracker that monitors input/output token counts against a configurable ceiling. If the budget is breached, Pi truncates the least relevant context blocks and retries automatically.
4. Diff-First Execution: Pi never generates raw file contents. It always outputs unified diffs. This reduces token waste, prevents full-file overwrites, and makes version control integration trivial.

These components are intentionally decoupled. You can swap the LLM gateway, replace the context resolver, or write custom diff validators without touching the core binary.

Examples & Code Walkthrough

Below is a production-ready TypeScript plugin that implements a pre-prompt hook. It enforces a security policy by blocking the LLM from modifying files in protected directories unless an explicit --override flag is passed. The plugin includes proper error boundaries, type safety, and inline documentation.

import { Plugin, HookContext, HookResult, ErrorCode } from "@pi/core";
import { existsSync, readFileSync } from "fs";
import { resolve } from "path";

export class SecurityBoundaryPlugin implements Plugin {
  public readonly name = "security-boundary";
  public readonly version = "1.0.0";

  constructor(private readonly protectedPaths: string[] = ["/core/", "/infra/"]) {}

  async onBeforeAssemble(ctx: HookContext): Promise<HookResult> {
    const targetPaths = ctx.manifest.files.map(f => f.path);
    const violations: string[] = [];

    for (const path of targetPaths) {
      if (this.protectedPaths.some(p => path.includes(p))) {
        violations.push(path);
      }
    }

    if (violations.length > 0 && !ctx.flags.override) {
      return {
        success: false,
        code: ErrorCode.POLICY_VIOLATION,
        message: `Refusing generation. Protected paths detected: ${violations.join(", ")}. Use --override to bypass.`,
        abort: true
      };
    }

    // Inject explicit boundary markers into the prompt context
    ctx.manifest.metadata.securityBoundaries = this.protectedPaths;
    return { success: true, code: ErrorCode.OK, message: "Security check passed." };
  }

  async onAfterGenerate(ctx: HookContext): Promise<HookResult> {
    // Validate that the diff does not accidentally touch protected paths
    const diffPaths = ctx.patch.extractModifiedPaths();
    const accidentalTouches = diffPaths.filter(p => 
      this.protectedPaths.some(bp => p.includes(bp))
    );

    if (accidentalTouches.length > 0) {
      return {
        success: false,
        code: ErrorCode.PATCH_VIOLATION,
        message: `