David Kong dd2202f54c Milestone 1.2: Register all four worktree tools (#15 )

## Summary
Register all four git worktree tools with correct TypeBox schemas and placeholder implementations.

## Changes
- Added `.pi/extensions/pi-worktree.ts` with four tool registrations:
  - `git_worktree_list` — no params, lists linked worktrees
  - `git_worktree_create` — path, branch?, create_branch? params
  - `git_worktree_switch` — target param for switching cwd
  - `git_worktree_remove` — path param for removing worktrees
- Each tool returns "Not implemented yet." placeholder response

## Testing
- [x] All four tools registered with correct TypeBox schemas
- [x] Calling each tool returns a response (placeholder)
- [ ] Extension loads without errors when pi starts (manual verification needed)

## Checklist
- [ ] Self-reviewed the diff
- [ ] Code follows project conventions
- [ ] Descriptive naming (no single-character variables)

Co-authored-by: David Kong <davkon@gmail.com>
Reviewed-on: #15

2026-07-24 12:31:29 +00:00

3.1 KiB

Raw Blame History

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