Pi Extensions

Pi Extensions — LLM Master Reference

Start Here (Read Order)

The guides/ and references/ directories contain deeper narratives and examples. Use them after scanning the three master docs above.

One-Line Directives

• Writing a new extension? → Read ARCHITECTURE.md §1–§5, then copy the matching pattern from PATTERNS.md.
• Extension is broken? → Check ANTI-PATTERNS.md first.
• Extension is slow to start? → references/startup-optimization.md — jiti bottleneck, .js vs .ts, discovery cost.
• Need TUI component? → PATTERNS.md §P12–§P14, then guides/02-paradigms.md for narrative.
• Need beautiful TUI rendering? → references/tui-beautiful-rendering.md — box drawing, overlays, badges, SVG widgets.
• Need multi-agent patterns? → references/extension-patterns-from-source.md — agent coordination, tasks, feeds.
• Need custom provider/OAuth? → PATTERNS.md §P19–§P20, then guides/07-advanced-patterns.md.
• Need RPC safety? → ANTI-PATTERNS.md §A2, then guides/05-rpc-mode.md.

Master Decision Trees

Which document do I need?

I need to understand how extensions work
  └─► ARCHITECTURE.md

I need working code to copy
  └─► PATTERNS.md

I need to know what NOT to do
  └─► ANTI-PATTERNS.md

I need a step-by-step first tutorial
  └─► guides/01-quickstart.md

I need deep narrative on tools/events/UI
  └─► guides/02-paradigms.md

I need state persistence strategies
  └─► guides/03-state.md

I need production architecture (workflows, memory)
  └─► guides/04-production.md

I need RPC mode specifics
  └─► guides/05-rpc-mode.md

I need pi internals (loader, runner, binding)
  └─► guides/06-internals.md

I need startup optimization, speed up extension loading
  └─► references/startup-optimization.md

I need provider plugins, OAuth, overrides
  └─► guides/07-advanced-patterns.md

Which paradigm should I use?

Need LLM to perform action? ───────────────► Tool (PATTERNS P2–P5)
Need user to type /command? ───────────────► Command (PATTERNS P6–P7)
Need keyboard shortcut? ───────────────────► Shortcut (guides/02-paradigms.md)
Need to react to system events? ───────────► Event handler (PATTERNS P8–P11)
Need interactive TUI? ─────────────────────► Custom UI (PATTERNS P12–P14)
Need to inject a model provider? ──────────► registerProvider (PATTERNS P19–P20)
Need to override a built-in tool? ─────────► Tool override (PATTERNS P4)

Which state persistence mechanism?

State should go to LLM context? ───────────► sendMessage({ customType, ... })
State is extension-private? ───────────────► appendEntry("customType", data)
State is user preference (cross-project)? ─► File in ~/.pi/agent/
State is project-local? ───────────────────► File in .pi/
State is temporary cache? ─────────────────► Local variable (reconstructed on reload)

Document Map

Master References (Read First)

Progressive Guides (Read as Needed)

Reference Docs

Tutorials

Examples

5-Minute Quick Test

Prerequisite: This skill is installed (cloned to skills/pi-extensions). Below creates a sample Extension, placed in ~/.pi/agent/extensions/ — separate from the skill directory.

# 1. Create the sample extension file
mkdir -p ~/.pi/agent/extensions
cat > ~/.pi/agent/extensions/hello.ts << 'EOF'
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (_args, ctx) => {
      ctx.ui.notify("Hello from Pi Extensions!", "success");
    },
  });
}
EOF

# 2. Test with -e flag (temporary load)
pi -e ~/.pi/agent/extensions/hello.ts
# Then type: /hello
#
# Tip: Extensions in ~/.pi/agent/extensions/ are auto-discovered.
#      The -e flag is only needed for temporary testing.

Quick Import Cheat Sheet

// Core types
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";

// Schema
import { Type } from "@sinclair/typebox";
import { StringEnum } from "@earendil-works/pi-ai";

// TUI
import { Container, Text, SelectList } from "@earendil-works/pi-tui";

// Utilities
import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { isToolCallEventType, isBashToolResult } from "@earendil-works/pi-coding-agent";

Hot Topics

Dynamic Model Injection

Use pi.registerProvider() for proxies, custom endpoints, or team-wide model configs. See PATTERNS.md §P19–P20 and guides/07-advanced-patterns.md.

Tool Override

Register a tool with the same name as a built-in (read, bash, edit, write) to wrap or replace it. See PATTERNS.md §P4.

Parallel Execution Safety

Custom tools that mutate files must use withFileMutationQueue() to avoid race conditions with built-in edit/write. See PATTERNS.md §P5 and ANTI-PATTERNS.md §A4.

RPC Safety

ctx.hasUI is true in RPC, but custom() returns undefined. Use select/confirm/input/editor for blocking dialogs that work in both modes. See ANTI-PATTERNS.md §A2 and guides/05-rpc-mode.md.

Master references: ARCHITECTURE · PATTERNS · ANTI-PATTERNS