9f4bf8c452
Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
132 lines
7.2 KiB
Markdown
132 lines
7.2 KiB
Markdown
# File Reference — Example Extensions
|
|
|
|
|
|
All paths relative to:
|
|
```
|
|
/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/examples/extensions/
|
|
```
|
|
|
|
### Lifecycle & Safety
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `protected-paths.ts` | Blocking writes to `.env`, `.git/`, `node_modules/` via `tool_call` |
|
|
| `dirty-repo-guard.ts` | Preventing session changes with uncommitted git changes |
|
|
|
|
### Custom Tools
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `todo.ts` | **Best example** — Stateful tool with persistence, custom rendering, command |
|
|
| `hello.ts` | Minimal tool registration |
|
|
| `question.ts` | Tool with `ctx.ui.select()` for user interaction |
|
|
| `questionnaire.ts` | Multi-question wizard with tab navigation |
|
|
| `tool-override.ts` | Overriding built-in `read` with logging/access control |
|
|
| `dynamic-tools.ts` | Registering tools after startup and at runtime |
|
|
| `truncated-tool.ts` | Output truncation with `truncateHead` |
|
|
| `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools |
|
|
| `antigravity-image-gen.ts` | Image generation tool |
|
|
| `ssh.ts` | Full SSH remote execution with pluggable operations |
|
|
|
|
### Commands & UI
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `commands.ts` | Basic command registration |
|
|
| `preset.ts` | Named presets (model, thinking, tools) with flag and command |
|
|
| `plan-mode/` | Full plan mode — commands, shortcuts, flags, widgets, status, tool management |
|
|
| `qna.ts` | Extract questions + `BorderedLoader` + `setEditorText` |
|
|
| `send-user-message.ts` | `pi.sendUserMessage()` for injecting user messages |
|
|
| `modal-editor.ts` | Vim-like modal editor via `CustomEditor` |
|
|
| `snake.ts` | Full game with custom UI, keyboard handling, persistence |
|
|
| `space-invaders.ts` | Full game with custom UI |
|
|
| `doom-overlay/` | DOOM running as an overlay at 35 FPS |
|
|
| `timed-confirm.ts` | Dialogs with `timeout` and `AbortSignal` |
|
|
| `overlay-test.ts` | Overlay compositing with inline inputs |
|
|
| `overlay-qa-tests.ts` | Comprehensive overlay tests: anchors, margins, stacking |
|
|
|
|
### System Prompt & Context
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `pirate.ts` | `before_agent_start` system prompt modification |
|
|
| `claude-rules.ts` | Loading rules from `.claude/rules/` into system prompt |
|
|
| `system-prompt-header.ts` | Displaying system prompt info |
|
|
| `input-transform.ts` | Transforming user input via `input` event |
|
|
| `inline-bash.ts` | Expanding `!{command}` patterns in prompts |
|
|
|
|
### Compaction & Sessions
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `custom-compaction.ts` | Custom compaction summary via `session_before_compact` |
|
|
| `trigger-compact.ts` | Triggering compaction at 100k tokens |
|
|
| `git-checkpoint.ts` | Git stash on turns, restore on fork |
|
|
| `bookmark.ts` | Labeling entries for `/tree` navigation |
|
|
| `session-name.ts` | Naming sessions for selector display |
|
|
|
|
### UI Components
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `custom-footer.ts` | `setFooter` with git branch and token stats |
|
|
| `custom-header.ts` | `setHeader` for custom startup header |
|
|
| `status-line.ts` | `setStatus` for footer indicators |
|
|
| `widget-placement.ts` | `setWidget` above and below editor |
|
|
| `notify.ts` | Desktop notifications via OSC 777 |
|
|
| `titlebar-spinner.ts` | Braille spinner in terminal title |
|
|
| `message-renderer.ts` | Custom message rendering with `registerMessageRenderer` |
|
|
| `model-status.ts` | `model_select` event for status bar |
|
|
| `mac-system-theme.ts` | Auto-sync theme with macOS dark/light mode |
|
|
|
|
### Providers
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `custom-provider-anthropic/` | Custom Anthropic provider with OAuth |
|
|
| `custom-provider-gitlab-duo/` | GitLab Duo via proxy |
|
|
| `custom-provider-qwen-cli/` | Qwen CLI with OAuth device flow |
|
|
|
|
### Communication
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `event-bus.ts` | Inter-extension communication via `pi.events` |
|
|
| `rpc-demo.ts` | All RPC-supported extension UI methods |
|
|
| `reload-runtime.ts` | Safe reload flow: command + LLM tool handoff |
|
|
| `shutdown-command.ts` | `ctx.shutdown()` for graceful exit |
|
|
| `file-trigger.ts` | File watcher injecting messages via `sendMessage` |
|
|
|
|
### Misc
|
|
| File | What It Demonstrates |
|
|
|------|---------------------|
|
|
| `with-deps/` | Extension with its own `package.json` and npm dependencies |
|
|
| `minimal-mode.ts` | Override built-in tool rendering for minimal display |
|
|
|
|
---
|
|
|
|
## Quick Reference: "I want to..."
|
|
|
|
| Goal | Approach | Key API | Example File |
|
|
|------|----------|---------|-------------|
|
|
| Block dangerous commands | Listen to `tool_call`, return `{ block: true }` | `pi.on("tool_call", ...)` | `protected-paths.ts` |
|
|
| Add a tool the LLM can use | Register a tool with schema and execute | `pi.registerTool({...})` | `todo.ts` |
|
|
| Add a slash command | Register a command with handler | `pi.registerCommand(...)` | `commands.ts` |
|
|
| Ask the user a question | Use dialog methods | `ctx.ui.select()`, `ctx.ui.confirm()` | `question.ts` |
|
|
| Show persistent status | Set footer status | `ctx.ui.setStatus(id, text)` | `status-line.ts` |
|
|
| Modify the system prompt | Hook `before_agent_start` | Return `{ systemPrompt: "..." }` | `pirate.ts` |
|
|
| Filter messages sent to LLM | Hook `context` event | Return `{ messages: [...] }` | — |
|
|
| Save state across restarts | Store in tool details or appendEntry | `details: {...}` / `pi.appendEntry(...)` | `todo.ts` |
|
|
| Custom compaction | Hook `session_before_compact` | Return `{ compaction: {...} }` | `custom-compaction.ts` |
|
|
| Build a full-screen UI | Use `ctx.ui.custom()` | Component with render/handleInput | `snake.ts` |
|
|
| Show a floating dialog | Use overlay mode | `ctx.ui.custom(..., { overlay: true })` | `overlay-test.ts` |
|
|
| Replace the input editor | Extend `CustomEditor` | `ctx.ui.setEditorComponent(...)` | `modal-editor.ts` |
|
|
| Override a built-in tool | Register tool with same name | `pi.registerTool({ name: "read" })` | `tool-override.ts` |
|
|
| Run tools via SSH | Use pluggable operations | `createBashTool(cwd, { operations })` | `ssh.ts` |
|
|
| Switch models programmatically | Find and set model | `pi.setModel(model)` | `preset.ts` |
|
|
| Register a custom provider | Provide config with models | `pi.registerProvider(...)` | `custom-provider-anthropic/` |
|
|
| Transform user input | Hook `input` event | Return `{ action: "transform", text }` | `input-transform.ts` |
|
|
| Inject messages | Send custom or user messages | `pi.sendMessage()` / `pi.sendUserMessage()` | `send-user-message.ts` |
|
|
| React to model changes | Hook `model_select` | `pi.on("model_select", ...)` | `model-status.ts` |
|
|
| Add a keyboard shortcut | Register a shortcut | `pi.registerShortcut("ctrl+x", ...)` | `plan-mode/` |
|
|
| Package for distribution | Add `pi` key to package.json | `"pi": { "extensions": [...] }` | See packages.md |
|
|
|
|
---
|
|
|
|
*This document was generated from the Pi extension documentation and examples. Source docs are at:*
|
|
```
|
|
/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/
|
|
/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/examples/extensions/
|
|
```
|