piexts

Personal workspace for building, testing, and iterating on custom Pi extensions.

Repository layout

piexts/
  extensions/
    handoff/              # Hybrid handoff extension (ported from breadcrumbs work)
  docs/
    quickstart.md
    references.md
    workflow-tips.md
  templates/
    extension-checklist.md

Quick start

cd piexts
pnpm install
pnpm typecheck

Run Pi with the handoff extension loaded:

cd extensions/handoff
pi

Pi reads pi.extensions from extensions/handoff/package.json and loads index.ts directly.

Current extension

• extensions/handoff
  • /handoff [goal] command with interactive fallback
  • streaming extraction UI (Ctrl+O expand, Esc cancel)
  • lineage custom messages (source + marker)
  • handoff tool (recommend-first; guarded execute config currently degrades to recommend)
  • configurable extractionTimeoutMs, postSwitchMode, handoffTool, toolBehavior

Config file:

• Global: ~/.pi/agent/extensions/handoff.json
• Project: .pi/extensions/handoff.json

Example:

{
  "handoffTool": true,
  "toolBehavior": "recommend",
  "postSwitchMode": "draft",
  "extractionTimeoutMs": 30000
}

Add another extension

1. Create extensions/<name>/
2. Add package.json with:
   • "pi": { "extensions": ["./index.ts"] }
3. Add index.ts default export (pi: ExtensionAPI) => { ... }
4. Add tsconfig.json extending ../../tsconfig.base.json
5. Run pnpm -r typecheck

Documentation + examples

See:

• docs/references.md for official Pi docs and example extension links.
• docs/workflow-tips.md for practical build/test workflow and gotchas.
• templates/extension-checklist.md before publishing or sharing.