Pi Extension Authoring

Use this before changing Pi extension code or debugging Pi startup warnings.

Canonical surfaces

• Repo-local joelclaw extensions: ~/Code/joelhooks/joelclaw/pi/extensions/<name>
• Active symlinks: ~/.pi/agent/extensions/<name> → repo-local source
• Package extensions: ~/.pi/agent/git/github.com/<owner>/<repo>
• Package config: ~/.pi/agent/settings.json
• Pi SDK/docs: global package under ~/.local/share/fnm/node-versions/*/installation/lib/node_modules/@earendil-works/pi-coding-agent/ (older installs used @mariozechner/pi-coding-agent)

Rules

1. Do not keep using captured session-bound objects after session replacement.
   • ctx.newSession(), ctx.fork(), ctx.switchSession(), and ctx.reload() invalidate old pi and ctx objects.
   • For replacement commands, move post-switch work into the method's withSession callback and use only the callback ctx.
   • For reload commands, treat await ctx.reload(); return; as terminal.