pi-worktrees/AGENTS.md

AGENTS.md — pi-worktree Extension

Project Structure

.pi/extensions/pi-worktree.ts    # Single-file extension (all tool + command logic)
README.md                        # User-facing documentation
DESIGN.md                        # Architecture and design decisions
DOMAIN.md                        # Domain concepts and terminology

Tech Stack

• Language: TypeScript
• Schema: TypeBox (@sinclair/typebox) for tool parameter schemas
• Runtime: pi coding agent extension API (ExtensionAPI, ExtensionContext)
• Git: native via pi.exec("git", [...]) — no external git packages
• No npm dependencies in v1 beyond what pi provides

Extension Entry Point

The extension is a single default-exported function:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // register tools and commands here
}

Tool Conventions

• Each tool is a Type.Object schema + async execute function.
• Execute signature: (toolCallId, params, signal, onUpdate, ctx)
• Always check result.exitCode !== 0 for git failures — surface the message with suggested fixes.
• Fail fast: refuse dangerous operations (existing paths, current branch, uncommitted changes) with clear messages and suggestions. No silent auto-correction.

Command Conventions

• Register via pi.registerCommand("name", { description, handler }).
• Use ctx.ui.select() for interactive pickers.
• Parse structured data from tool results (not raw text).

State Management

• Tools are stateless — each call works independently based on current git state.
• Session memory is ephemeral (per pi process lifetime) for back-switching behavior only.

Error Handling Pattern

if (result.exitCode !== 0) {
  return {
    content: [{ type: "text", text: `Error: ${result.stderr}. Suggestion: <fix>` }],
    isError: true
  };
}

Always include a suggested fix in error messages.

Validation Checklist

• Extension loads without errors when pi starts
• All four tools registered with correct signatures
• Error paths return isError: true with helpful messages
• /worktree command shows interactive picker
• Branch display updates after switching worktrees
• No external dependencies beyond TypeBox + pi SDK