Intermediate

// package.json — the pi-extension field is what Pi looks for when scanning
// the extensions directory. Without it, Pi ignores the package.
{
  "name": "pi-ext-grep-symbols",
  "version": "1.0.0",
  "description": "Search for symbols across a codebase",
  "main": "dist/index.js", // => Compiled output — Pi loads this file
  "pi-extension": {
    "entry": "dist/index.js", // => Pi reads this field to find the entry point
    "version": "1" // => Extension API version (currently "1")
  },
  "scripts": {
    "build": "tsc", // => Compile TypeScript to dist/
    "watch": "tsc --watch" // => Watch mode for hot-reload during development
  },
  "dependencies": {},
  "devDependencies": {
    "typescript": "^5.4.0",
    "@earendil-works/pi-coding-agent": "^0.75.0" // => Types for Tool, register(), etc.
  }
}

// index.ts — the extension entry point
// Pi imports this module and calls the default export with the Pi API object
 
import { PiExtensionAPI, Tool } from "@earendil-works/pi-coding-agent";
// => Import types from the Pi package
 
// Define the tool your extension provides
const grepSymbolsTool: Tool = {
  name: "grep_symbols", // => Name the LLM uses in function-calling
  description:
    "Search for a TypeScript or JavaScript symbol across all source files. " +
    "Use this to find where a function, class, or variable is defined or used.",
  // => LLM reads this description to decide when to call
  parameters: {
    type: "object",
    properties: {
      symbol: {
        type: "string", // => The symbol name to search for
        description: "Symbol name to search (function, class, variable, type)",
      },
      path: {
        type: "string", // => Directory to search in
        description: "Directory to search in (default: current directory)",
      },
    },
    required: ["symbol"], // => path is optional; symbol is required
  },
  execute: async ({ symbol, path = "." }, { bash }) => {
    // => execute receives tool arguments and Pi's built-in tool helpers
    // => bash() is Pi's Bash tool, available to extensions for shell execution
 
    const result = await bash(`grep -r --include='*.ts' --include='*.js' -n "${symbol}" ${path}`); // => grep with TypeScript/JS file filter, line numbers
 
    if (!result.stdout.trim()) {
      return `No occurrences of '${symbol}' found in ${path}`;
      // => Return a string — Pi sends this as tool_result
    }
 
    return result.stdout; // => Return grep output; LLM analyzes the matches
  },
};
 
// Extension entry point — Pi calls this function when loading the extension
export default function setup(api: PiExtensionAPI): void {
  api.register(grepSymbolsTool); // => Register the tool with Pi's session
  // => Tool is now available to the LLM immediately
}

# Compile the TypeScript extension
npm run build
# => tsc -p tsconfig.json
# => (Output written to dist/index.js)
 
# Install the extension into Pi's extensions directory
npm install --prefix ~/.pi/extensions .
# => (Links or copies the built package into ~/.pi/extensions/node_modules/pi-ext-grep-symbols/)
 
# Start Pi — extension loads automatically
pi
# => Pi v0.75.4
# => Extensions loaded: pi-ext-grep-symbols
# => Provider: anthropic · Model: claude-sonnet-4-5 · Context: 0 tokens

import { Tool, PiExtensionAPI } from "@earendil-works/pi-coding-agent";
 
// A tool that runs the project's test suite and returns structured results
const runTestsTool: Tool = {
  name: "run_tests",
 
  // Good description: specific about what it does, when to use it, what it returns
  description:
    "Run the project's Vitest test suite and return a structured summary of " +
    "results including pass/fail counts and failure details. Use this after " +
    "making code changes to verify the change does not break existing tests.",
  // => LLM uses this paragraph to decide: "should I call run_tests now?"
  // => The "Use this after making code changes" phrase guides the LLM's timing
 
  parameters: {
    type: "object",
    properties: {
      filter: {
        type: "string",
        description:
          "Optional test name filter — only run tests matching this string. " +
          "Example: 'auth' runs only tests with 'auth' in their name.",
        // => Description guides LLM on when to set this field
      },
      bail: {
        type: "boolean",
        description:
          "If true, stop after the first test failure. Useful for fast feedback " +
          "when debugging a specific failure. Default: false.",
      },
    },
    required: [], // => All parameters are optional — LLM can call with {}
  },
 
  execute: async ({ filter, bail = false }, { bash }) => {
    // Build the vitest command from parameters
    const filterFlag = filter ? `--reporter=verbose -t "${filter}"` : "";
    // => -t is Vitest's test name filter flag
 
    const bailFlag = bail ? "--bail" : ""; // => --bail stops after first failure
 
    const result = await bash(`npx vitest run ${filterFlag} ${bailFlag} --reporter=json 2>&1`); // => --reporter=json gives structured output
    // => 2>&1 captures stderr too (Vitest logs there)
 
    // Parse Vitest JSON output into a readable summary
    try {
      const report = JSON.parse(result.stdout);
      // => Vitest JSON output has numPassedTests, numFailedTests, etc.
      const passed = report.numPassedTests; // => Count of passing tests
      const failed = report.numFailedTests; // => Count of failing tests
      const failures = report.testResults // => Array of test file results
        .flatMap((f: any) => f.testResults) // => Flatten to individual test results
        .filter((t: any) => t.status === "failed")
        .map((t: any) => `  FAIL: ${t.fullName}\n    ${t.failureMessages[0]}`)
        .join("\n"); // => Format failures for LLM readability
 
      return [`Tests: ${passed} passed, ${failed} failed`, failures ? `\nFailures:\n${failures}` : ""].join("");
      // => Returns: "Tests: 47 passed, 2 failed\nFailures:\n  FAIL: auth > validates JWT..."
    } catch {
      return result.stdout; // => Fallback: return raw output if JSON parse fails
    }
  },
};
 
export default function setup(api: PiExtensionAPI): void {
  api.register(runTestsTool); // => Adds run_tests to the LLM's tool schema
  // => From this point forward, the LLM can call run_tests on any turn
}

// Error handling pattern for tool execute functions
execute: async ({ symbol, path = "." }, { bash }) => {
  try {
    const result = await bash(`grep -r "${symbol}" ${path}`);
 
    if (result.exitCode !== 0 && !result.stdout) {
      // => exitCode non-zero with no output means grep found nothing
      return `No matches for '${symbol}' in ${path}`;
                                          // => Descriptive return — LLM understands and adapts
    }
 
    return result.stdout;
  } catch (error) {
    // => Catch unexpected errors (permission denied, path not found, etc.)
    return `grep_symbols failed: ${(error as Error).message}`;
                                          // => Return error as string — LLM sees this as tool_result
                                          // => LLM can then decide to try a different path or approach
  }
},

<!-- Example skill file: .pi/skills/vitest-conventions/SKILL.md -->
<!-- This skill teaches the agent how the project uses Vitest -->
 
# Vitest Test Conventions for This Project
 
## Test File Location
 
Tests live next to the source files they test, with a `.test.ts` suffix:
 
- `src/auth/jwt.ts` → `src/auth/jwt.test.ts`
- `src/router/tasks.ts` → `src/router/tasks.test.ts`
 
Never place tests in a separate `tests/` or `__tests__/` directory.
 
## Test Structure
 
Each test file follows this structure:
 
```typescript
import { describe, it, expect, beforeEach, vi } from "vitest";
 
describe("ModuleName", () => {
  beforeEach(() => {
    vi.clearAllMocks(); // Always clear mocks between tests
  });
 
  describe("functionName", () => {
    it("does the expected behavior when given valid input", () => {
      // Arrange
      // Act
      // Assert with expect()
    });
 
    it("throws when given invalid input", () => {
      expect(() => functionName(badInput)).toThrow("Expected error message");
    });
  });
});
```

# AGENTS.md excerpt — skill injection configuration
 
## Pi Skills Configuration
 
skills:
threshold: 0.72 # Relevance cutoff (0.0–1.0; default: 0.70)
max-injected: 3 # Maximum skills injected per turn (default: 5)
always-inject: # Skills always injected regardless of score - project-conventions
never-inject: # Skills never injected (useful for debugging) - legacy-api-reference

// You can also control skill injection programmatically in an extension
 
import { PiExtensionAPI, Skill } from "@earendil-works/pi-coding-agent";
 
const databaseSkill: Skill = {
  name: "database-conventions",
  content: `
# Database Access Conventions
 
Always use Prisma client for database access. Never write raw SQL.
Connection string is in DATABASE_URL environment variable.
Migrations live in prisma/migrations/ — never edit them directly.
  `,
  // => Inline skill defined in TypeScript — useful for extension-specific guidance
  alwaysInject: false, // => Let relevance scoring decide injection
  priority: 1.0, // => Higher priority = preferred over same-score skills
};
 
export default function setup(api: PiExtensionAPI): void {
  api.registerSkill(databaseSkill); // => Register inline skill alongside SKILL.md files
  // => Both types participate in relevance scoring
}

# Run Pi in verbose mode to see skill injection decisions
pi --verbose
# => [skills] Scoring 4 skills for turn 1
# => [skills] vitest-conventions: 0.84 (INJECT — above threshold 0.70)
# => [skills] database-conventions: 0.31 (skip — below threshold)
# => [skills] git-workflow: 0.22 (skip — below threshold)
# => [skills] project-conventions: always-inject (INJECT)
# => [skills] Injecting 2 skills (total: 847 tokens)

# Monitor context growth during a session
/stats
# => Session: 2026-05-21T10-15-00__implement-search
# => Turns: 42
# => Context tokens: 156,832 / 200,000 (78.4%)
# => Auto-compaction will trigger at ~160,000 tokens
# => Estimated cost so far: $0.31
 
# Trigger manual compaction before the limit
/compact
# => Compacting 34 older turns...
# => Summary generated (1,247 tokens)
# => Before: 156,832 tokens (42 turns)
# => After: 24,391 tokens (8 turns verbatim + summary)
# => Saved: 132,441 tokens

// Configure compaction behavior in an extension or AGENTS.md
 
// In AGENTS.md:
// pi-config:
//   context:
//     compaction-threshold: 0.75    # Trigger at 75% of model limit (default: 0.80)
//     verbatim-tail: 12             # Keep last 12 turns verbatim (default: 8)
//     compaction-model: claude-haiku-4-5  # Use a cheaper model for compaction itself
 
// In an extension — programmatically control compaction:
import { PiExtensionAPI } from "@earendil-works/pi-coding-agent";
 
export default function setup(api: PiExtensionAPI): void {
  // Register a slash command that triggers compaction + reports savings
  api.registerCommand({
    name: "compact-report", // => /compact-report in the TUI
    description: "Compact context and show token savings report",
    execute: async (_, { session, compact }) => {
      const before = session.contextTokens; // => Token count before compaction
      await compact(); // => Trigger compaction
      const after = session.contextTokens; // => Token count after
      const saved = before - after; // => Tokens saved
 
      return [
        `Compaction complete`,
        `Before: ${before.toLocaleString()} tokens`,
        `After:  ${after.toLocaleString()} tokens`,
        `Saved:  ${saved.toLocaleString()} tokens (${Math.round((saved / before) * 100)}%)`,
      ].join("\n");
    },
  });
}

# Development session: you've just completed implementing a JWT auth module
# Session: 2026-05-21T09-00-00__implement-jwt-auth (22 turns, 34,000 tokens)
 
# Branch from the current point for review
/branch review-jwt-security
# => Branched from: implement-jwt-auth (turn 22)
# => New session: 2026-05-21T11-30-00__review-jwt-security
# => Context: 34,000 tokens (22 turns — identical to branch point)
# => (You are now in the review branch)
 
# In the review branch, ask for a security-focused review
# "Review the JWT authentication implementation for security issues.
#  Check token expiry validation, algorithm validation, and secret key handling."
 
# The agent reads the relevant files and produces findings:
# => Tool call: Read("src/auth/jwt.ts")
# => Tool call: Read("src/auth/middleware.ts")
# => Tool call: Bash("grep -n 'secret\\|key\\|algorithm' src/auth/jwt.ts")
# => Response: "I found 3 issues: [1] The algorithm is not validated... [2] ..."
 
# Share the review session for the PR
/share --title "JWT auth security review"
# => Session shared: https://gist.github.com/yourusername/abc123...
 
# Return to the development session (it is unchanged)
/load implement-jwt-auth
# => Resuming session: implement-jwt-auth (22 turns, 34,000 tokens)
# => (Development session is exactly as you left it)

# Start Pi in RPC mode — reads from stdin, writes to stdout
pi --rpc
# => (Pi is now listening for JSON-RPC messages on stdin)
# => (No TUI rendered — pure stdin/stdout protocol)
 
# Send a run request (in a separate terminal or from a caller process)
echo '{"jsonrpc":"2.0","id":1,"method":"run","params":{"message":"List TypeScript files in src/"}}' | pi --rpc
# => {"jsonrpc":"2.0","id":1,"result":{
# =>   "response":"Here are the TypeScript files in src/:\n- auth.ts\n- router.ts\n- index.ts",
# =>   "tool_calls":[
# =>     {"name":"Bash","input":{"command":"find src/ -name '*.ts'"},"result":"src/auth.ts\nsrc/router.ts\nsrc/index.ts\n"}
# =>   ],
# =>   "tokens":{"input":342,"output":67}
# => }}

# Calling Pi's RPC mode from Python
import subprocess
import json
 
class PiRPCClient:
    def __init__(self, cwd: str, model: str = None):
        # Start Pi in RPC mode as a subprocess
        cmd = ["pi", "--rpc", "--cwd", cwd]
        if model:
            cmd.extend(["--model", model])      # => Optional model override
 
        self.process = subprocess.Popen(
            cmd,
            stdin=subprocess.PIPE,              # => We write JSON-RPC to stdin
            stdout=subprocess.PIPE,             # => We read JSON-RPC from stdout
            text=True,
        )
        self._request_id = 0
 
    def run(self, message: str) -> dict:
        self._request_id += 1
        request = {
            "jsonrpc": "2.0",
            "id": self._request_id,             # => Unique ID per request for correlation
            "method": "run",
            "params": {"message": message},
        }
 
        # Send request to Pi's stdin
        self.process.stdin.write(json.dumps(request) + "\n")
        self.process.stdin.flush()              # => Flush required — Pi reads line by line
 
        # Read response from Pi's stdout
        line = self.process.stdout.readline()  # => Blocks until Pi finishes the turn
        return json.loads(line)                # => Parse JSON-RPC response
 
    def close(self):
        self.process.terminate()
 
# Usage
client = PiRPCClient(cwd="/path/to/project")
 
result = client.run("What is the main entry point of this application?")
# => result["result"]["response"] = "The main entry point is src/index.ts..."
# => result["result"]["tool_calls"] = [{"name": "Bash", "input": {...}, "result": "..."}]
 
client.close()

import { Agent, AnthropicProvider, Tool } from "@earendil-works/pi-agent-core";
 
// Define the tools your embedded agent will use
const readTool: Tool = {
  name: "read_file",
  description: "Read the contents of a file",
  parameters: {
    type: "object",
    properties: {
      path: { type: "string", description: "File path to read" },
    },
    required: ["path"],
  },
  execute: async ({ path }) => {
    const { readFile } = await import("fs/promises");
    return readFile(path, "utf-8"); // => Reads file, returns content as string
  },
};
 
const bashTool: Tool = {
  name: "bash",
  description: "Execute a shell command",
  parameters: {
    type: "object",
    properties: {
      command: { type: "string" },
    },
    required: ["command"],
  },
  execute: async ({ command }) => {
    const { exec } = await import("child_process");
    const { promisify } = await import("util");
    const execAsync = promisify(exec);
 
    const { stdout, stderr } = await execAsync(command);
    // => Executes command, captures stdout + stderr
    return stdout || stderr; // => Return whichever has content
  },
};
 
// Create and configure the agent
const agent = new Agent({
  provider: new AnthropicProvider({
    apiKey: process.env.ANTHROPIC_API_KEY!, // => API key from environment
    model: "claude-sonnet-4-5", // => Model to use for this agent
  }),
  systemPrompt: `You are a code review agent. Read source files and identify
issues. Write findings to review.md. Do not modify source files.`,
  // => Custom system prompt — replaces Pi's default
  tools: [readTool, bashTool], // => Register tools for this agent instance
  maxTurns: 20, // => Safety limit — stop after 20 tool call turns
});
 
// Run the agent on a task and get the result
async function reviewFile(filePath: string): Promise<string> {
  const result = await agent.run(`Review ${filePath} for code quality issues and security vulnerabilities.`);
  // => agent.run() executes the full agentic loop:
  // => 1. Send system prompt + user message to LLM
  // => 2. If LLM calls a tool, execute it, feed result back
  // => 3. Repeat until LLM produces a final text response
  // => 4. Return the final text response
 
  return result.response; // => Final LLM text response (the review)
}
 
// Call the agent
const review = await reviewFile("src/auth/jwt.ts");
console.log(review);
// => "I found 2 issues in src/auth/jwt.ts:
// => 1. [HIGH] The JWT algorithm is not validated against an allowlist...
// => 2. [MEDIUM] The token expiry is set to 7 days — consider shorter-lived tokens..."

// Using Agent for a multi-turn conversation from code
const agent = new Agent({ provider, systemPrompt, tools });
 
// First turn
await agent.run("Read package.json and tell me the project name");
// => "This project is named 'my-api' (version 1.2.3)."
 
// Second turn — agent has context from the first turn
await agent.run("What scripts are defined in package.json?");
// => "The package.json defines: start, build, test, and lint scripts."
// => (Agent already has package.json contents in context from first turn)
 
// Access conversation history
console.log(agent.messages.length);
// => 6 (2 user turns + 2 assistant turns + 2 tool turns for the Read calls)

import { TUI, Box, Text, Input, ScrollPane } from "@earendil-works/pi-tui";
 
// Create a simple TUI application
const app = new TUI({
  fullscreen: true, // => Take over the entire terminal
  title: "My Pi Extension Dashboard",
});
 
// Define a layout with a scrollable output pane and an input field
const layout = app.createLayout({
  direction: "column", // => Stack children vertically
  children: [
    new ScrollPane({
      id: "output", // => Reference this pane by id to update content
      flex: 1, // => Take all available vertical space
      content: [], // => Start empty — we'll push content here
    }),
    new Box({
      height: 3, // => Fixed height for the input area
      border: "single", // => Draw a single-line border around the input
      children: [
        new Input({
          id: "input",
          placeholder: "Type a command...",
          onSubmit: (value) => handleInput(value),
          // => Called when user presses Enter
        }),
      ],
    }),
  ],
});
 
app.render(layout); // => Draw the initial layout to the terminal
 
// Update the output pane with new content (differential rendering)
function appendOutput(text: string): void {
  const outputPane = app.getComponent<ScrollPane>("output");
  outputPane.push(new Text({ content: text }));
  // => Only the new Text node is redrawn
  // => Existing content is not redrawn (differential)
  outputPane.scrollToBottom(); // => Auto-scroll to show newest content
  app.render(); // => Apply the diff to the terminal
}

import { PiExtensionAPI, TUIComponent, Box, Text } from "@earendil-works/pi-coding-agent";
 
// A custom TUI component that shows live test status
class TestStatusPane implements TUIComponent {
  private status: "idle" | "running" | "passing" | "failing" = "idle";
  private summary: string = "";
 
  // Pi calls render() when the component needs to draw itself
  render(): Box {
    const statusColor = {
      idle: "gray",
      running: "yellow",
      passing: "green",
      failing: "red",
    }[this.status];
    // => Map status to a terminal color
 
    return new Box({
      border: "single",
      title: "Test Status",
      children: [
        new Text({
          content: this.status.toUpperCase(),
          color: statusColor, // => pi-tui handles terminal color codes
        }),
        new Text({ content: this.summary }),
      ],
    });
  }
 
  // Update the component's state (triggers re-render)
  update(status: typeof this.status, summary: string): void {
    this.status = status;
    this.summary = summary;
    // => Pi will call render() on the next frame
  }
}
 
export default function setup(api: PiExtensionAPI): void {
  const testPane = new TestStatusPane();
 
  // Register the component — Pi adds it to the TUI layout
  api.registerComponent({
    id: "test-status",
    position: "sidebar", // => Display in Pi's sidebar area
    component: testPane,
  });
 
  // Update the component from a tool's execute function
  api.register({
    name: "run_tests",
    description: "Run tests and update the test status pane",
    parameters: { type: "object", properties: {}, required: [] },
    execute: async (_, { bash }) => {
      testPane.update("running", "Running...");
      // => Update pane immediately when tests start
 
      const result = await bash("npx vitest run --reporter=json 2>&1");
 
      try {
        const report = JSON.parse(result.stdout);
        const passed = report.numPassedTests;
        const failed = report.numFailedTests;
 
        testPane.update(failed > 0 ? "failing" : "passing", `${passed} passed, ${failed} failed`);
        // => Update pane with results
        return `Tests: ${passed} passed, ${failed} failed`;
      } catch {
        testPane.update("failing", "Parse error");
        return result.stdout;
      }
    },
  });
}

# Inspect Pi's shrinkwrap file — this locks every transitive dependency
cat "$(npm root -g)/@earendil-works/pi-coding-agent/npm-shrinkwrap.json" | jq '.lockfileVersion'
# => 3   ← npm lockfile version 3 (npm 7+)
 
# Verify package integrity against the shrinkwrap
npm audit --prefix "$(npm root -g)/@earendil-works/pi-coding-agent"
# => found 0 vulnerabilities
# => (Pi's shrinkwrap pins versions that are CVE-clean as of the release date)
 
# Check an individual package's integrity hash
cat "$(npm root -g)/@earendil-works/pi-coding-agent/npm-shrinkwrap.json" | \
  jq '.packages["node_modules/some-dep"].integrity'
# => "sha512-AbCdEf..." ← SHA-512 hash of the published package tarball
# => npm verifies this hash on install — tampered packages will not install

# In your extension's package.json, pin ALL dependencies to exact versions
# (No ^ or ~ prefixes — exact pins only)
# package.json:
# {
#   "dependencies": {
#     "some-package": "1.2.3"    ← exact, not "^1.2.3" or "~1.2.3"
#   }
# }
 
# Generate a shrinkwrap file for your extension before publishing
cd your-extension/
npm shrinkwrap
# => wrote npm-shrinkwrap.json with 47 packages
 
# Audit your extension's dependencies
npm audit
# => found 0 vulnerabilities
# => (Fix any findings before publishing — do not ship extensions with known CVEs)
 
# Pin your TypeScript and Node.js versions for reproducibility
# .nvmrc or .node-version in your extension root:
echo "20.19.0" > .node-version
# => Users running your extension on Node.js 20.19.0 have the same behavior as you

// Supply-chain-hardened extension: explicit imports, no dynamic require()
 
// GOOD — static import, resolved at build time
import { execSync } from "child_process";
// => Static import — bundler can verify this
 
// BAD — dynamic require with variable input is a supply-chain risk
// const mod = require(userProvidedModuleName);
// => Never do this in an extension — dynamic require with external input
// => can load arbitrary code if the input is not strictly validated
 
// GOOD — if you must load modules dynamically, validate the name against an allowlist
const ALLOWED_FORMATTERS = ["prettier", "eslint", "tsc"] as const;
type Formatter = (typeof ALLOWED_FORMATTERS)[number];
 
async function runFormatter(name: Formatter, file: string): Promise<string> {
  // => TypeScript type ensures 'name' is one of the three allowed strings
  // => The union type is the allowlist — nothing outside it can pass type checking
  const { execAsync } = await import("./utils");
  return execAsync(`npx ${name} ${file}`);
}

import { PiRPCClient } from "./pi-rpc-client"; // The Python client pattern from Section 23, in TS
 
// Orchestrator: run two specialized agents in parallel
async function parallelCodeAnalysis(sourcePath: string): Promise<void> {
  // Agent 1: security review — specialized system prompt, read-only tools
  const securityAgent = new PiRPCClient({
    cwd: sourcePath,
    systemPromptFile: ".pi/security-review-system.md",
    // => Loads a system prompt focused on security
    model: "claude-opus-4-5", // => Use stronger model for security analysis
  });
 
  // Agent 2: performance review — different specialization, parallel execution
  const perfAgent = new PiRPCClient({
    cwd: sourcePath,
    systemPromptFile: ".pi/perf-review-system.md",
    model: "claude-sonnet-4-5", // => Lighter model for performance review
  });
 
  // Start both agents in parallel — they run simultaneously, sharing no state
  const [securityResult, perfResult] = await Promise.all([
    securityAgent.run(`Review ${sourcePath}/src/auth/ for security issues`),
    perfAgent.run(`Review ${sourcePath}/src/db/ for performance issues`),
  ]);
  // => Both RPC calls run concurrently
  // => Each agent has its own Pi session, its own context, its own tool calls
  // => No shared state between agents — fully isolated
 
  // Aggregate results
  console.log("Security findings:", securityResult.response);
  console.log("Performance findings:", perfResult.response);
 
  // Clean up
  securityAgent.close();
  perfAgent.close();
}
 
// Pipeline pattern: agent A generates, agent B reviews
async function generateAndReview(spec: string): Promise<void> {
  const generatorAgent = new PiRPCClient({
    cwd: "/project",
    systemPrompt: "You are a TypeScript developer. Write clean, typed code.",
  });
 
  // Step 1: generate
  const generated = await generatorAgent.run(`Implement the following spec and write it to src/: ${spec}`);
  // => Generator agent writes files to src/
 
  // Step 2: review what was generated (new agent, starts fresh)
  const reviewerAgent = new PiRPCClient({
    cwd: "/project",
    systemPrompt: "You are a code reviewer. Identify bugs and improvements.",
  });
 
  const review = await reviewerAgent.run(`Review the files recently added to src/ and report issues.`);
  // => Reviewer agent reads the files the generator wrote and produces findings
  // => Reviewer has no context of the generator's session — independent assessment
 
  console.log("Generated:", generated.response);
  console.log("Review:", review.response);
}

<!-- AGENTS.md with template variables -->
 
## Project: {{PROJECT_NAME}}
 
Environment: {{ENVIRONMENT}}
Database: {{DATABASE_URL}}
API base: {{API_BASE_URL}}
 
## Current Task Context
 
Branch: {{GIT_BRANCH}}
Last commit: {{GIT_COMMIT_SHORT}}
Files changed: {{GIT_CHANGED_FILES}}
 
<!-- Pi fills {{...}} variables from environment variables or a .pi-vars file -->
<!-- Variables not found are left as-is and logged as a warning -->

# Variables filled from environment variables
export PROJECT_NAME="TaskManager API"
export ENVIRONMENT="development"
export DATABASE_URL="postgresql://localhost:5432/taskmanager_dev"
export API_BASE_URL="http://localhost:3000"
 
# Or from a .pi-vars file (not committed — add to .gitignore)
cat .pi-vars
# => PROJECT_NAME=TaskManager API
# => ENVIRONMENT=development
# => DATABASE_URL=postgresql://localhost:5432/taskmanager_dev
 
pi
# => Pi v0.75.4
# => Template variables resolved: PROJECT_NAME, ENVIRONMENT, DATABASE_URL, API_BASE_URL, ...
# => Git variables injected: GIT_BRANCH=main, GIT_COMMIT_SHORT=a1b2c3d, GIT_CHANGED_FILES=3
# => Loaded AGENTS.md (487 tokens — after variable substitution)

// Dynamic injection via an extension — inject API schema only when relevant
import { PiExtensionAPI } from "@earendil-works/pi-coding-agent";
import { readFile } from "fs/promises";
 
export default function setup(api: PiExtensionAPI): void {
  // Register a turn hook — called before each LLM turn
  api.onBeforeTurn(async (turn, { inject }) => {
    const message = turn.userMessage.toLowerCase();
 
    // Only inject the OpenAPI schema when the user is asking about the API
    if (message.includes("api") || message.includes("endpoint") || message.includes("route")) {
      const schema = await readFile("openapi.yaml", "utf-8");
      // => Read the schema file on demand
 
      inject({
        content: `# API Schema\n\`\`\`yaml\n${schema}\n\`\`\``,
        position: "before-message", // => Inject before the user's message in context
        label: "openapi-schema", // => Shown in verbose logs for debugging
      });
      // => Schema is in context for this turn only
      // => Not injected on turns where the user is not asking about the API
    }
  });
}

import { createProvider, Message, ToolDefinition } from "@earendil-works/pi-ai";
 
// Create a provider — swap one line to change providers
const provider = createProvider("anthropic", {
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-sonnet-4-5",
});
// => Identical interface for: createProvider("openai", {...})
// =>                          createProvider("google", {...})
// =>                          createProvider("ollama", {...})
 
// Define tools in pi-ai's unified format
const tools: ToolDefinition[] = [
  {
    name: "get_weather",
    description: "Get current weather for a city",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string" },
      },
      required: ["city"],
    },
  },
];
 
// Make a single LLM call with tools
const messages: Message[] = [{ role: "user", content: "What is the weather in Jakarta?" }];
 
const response = await provider.call({
  messages,
  tools, // => Tools are normalized to provider's function-calling format
  systemPrompt: "You are a helpful assistant.",
});
// => response.type is "text" or "tool_calls"
 
if (response.type === "tool_calls") {
  for (const call of response.toolCalls) {
    console.log(call.name); // => "get_weather"
    console.log(call.arguments); // => { city: "Jakarta" }
    // => Execute the tool and feed result back...
  }
}

import { createProvider, withFailover } from "@earendil-works/pi-ai";
 
const primary = createProvider("anthropic", {
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-sonnet-4-5",
});
 
const backup = createProvider("openai", {
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o",
});
 
// Wrap the primary provider with automatic failover
const provider = withFailover(primary, {
  fallback: backup, // => Use backup when primary fails
  retries: 2, // => Retry primary 2 times before switching
  onFailover: (error) => {
    console.warn(`Failover triggered: ${error.message}`);
    // => Log when failover occurs
  },
});
// => provider.call() now automatically retries primary twice, then uses backup
// => Your code doesn't change — same interface whether primary or backup responds

import { Provider, ProviderRequest, ProviderResponse } from "@earendil-works/pi-ai";
 
// Custom provider for a hypothetical company-internal LLM API
class InternalLLMProvider implements Provider {
  constructor(
    private apiEndpoint: string,
    private authToken: string,
  ) {}
 
  async call(request: ProviderRequest): Promise<ProviderResponse> {
    // Translate from pi-ai's normalized format to your API's format
    const internalRequest = {
      prompt: request.systemPrompt + "\n" + request.messages.map((m) => m.content).join("\n"),
      functions: request.tools?.map((t) => ({ name: t.name, schema: t.parameters })),
      max_tokens: 4096,
    };
 
    const res = await fetch(this.apiEndpoint, {
      method: "POST",
      headers: { Authorization: `Bearer ${this.authToken}` },
      body: JSON.stringify(internalRequest),
    });
 
    const data = await res.json();
 
    // Translate response back to pi-ai's normalized format
    if (data.function_call) {
      return {
        type: "tool_calls",
        toolCalls: [{ name: data.function_call.name, arguments: data.function_call.args }],
      };
    }
    return { type: "text", content: data.generated_text };
  }
}