AGENTS.md — pi-worktree Extension

Repo Details

Property	Value
Host	`git.excelera.net`
Remote	`https://git.excelera.net/david/pi-worktrees.git`
Owner	david
Repo	pi-worktrees

Using `fj` CLI to Pull Issues

This repo uses the fj CLI tool (Forgejo CLI) for issue operations. It's auto-detected from the git remote, so -H is optional inside this repo:

# Search open issues in this repo
fj issue search --repo pi-worktrees

# View a specific issue
fj issue view <ISSUE_NUM>

# List all open issues
fj issue search --state open

Prerequisites

fj must be installed and authenticated (fj whoami)
Credentials stored at ~/.local/share/forgejo-cli/keys.json
Auth via OAuth login or application token on git.excelera.net

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

3.1 KiB Raw Blame History