Build, debug, and maintain Pi extensions safely. Use when editing ~/.pi/agent/extensions, joelclaw/pi/extensions, pi-tools extensions, or any code that uses the Pi ExtensionAPI, hooks, tools, commands, widgets, session replacement, reload, custom messages, or extension package updates.
90%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Use this before changing Pi extension code or debugging Pi startup warnings.
~/Code/joelhooks/joelclaw/pi/extensions/<name>~/.pi/agent/extensions/<name> → repo-local source~/.pi/agent/git/github.com/<owner>/<repo>~/.pi/agent/settings.json~/.local/share/fnm/node-versions/*/installation/lib/node_modules/@earendil-works/pi-coding-agent/ (older installs used @mariozechner/pi-coding-agent)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.withSession callback and use only the callback ctx.await ctx.reload(); return; as terminal.Do not call pi.sendMessage() from delayed session_start callbacks.
pi/ctx, cache the plain result, then inject through before_agent_start by returning { message }.Promise.race budget if the result may not be ready.Use pi.registerTool(), not old APIs.
pi.addTool() is gone.details. No timers, functions, sockets, or class instances.Optional dependencies must be lazy.
createRequire() inside guarded functions.One active copy per extension.
package.json no longer lists it in pi.extensions before ignoring it.let cachedMessage: HiddenCustomMessage | null | undefined;
let messagePromise: Promise<HiddenCustomMessage | null> | null = null;
let delivered = false;
pi.on("session_start", (_event, ctx) => {
delivered = false;
cachedMessage = undefined;
const sessionId = ctx.sessionManager?.getSessionId?.() ?? null;
messagePromise = buildMessageWithoutCapturedPi(sessionId).then((message) => {
cachedMessage = message;
return message;
});
});
pi.on("before_agent_start", async (event) => {
const message = await Promise.race([
messagePromise,
new Promise<null>((resolve) => setTimeout(() => resolve(null), 250)),
]);
if (message && !delivered) {
delivered = true;
return {
systemPrompt: event.systemPrompt,
message,
};
}
return { systemPrompt: event.systemPrompt };
});Run the cheap gates first:
bun --check path/to/extension/index.ts
PI_OFFLINE=1 pi --help >/tmp/pi-help.out 2>/tmp/pi-help.err
rg -n "Skill conflicts|cannot load optional dependency|stale after session|<extension-name>" /tmp/pi-help.err /tmp/pi-help.outFor package updates:
# Update Pi plus settings-managed packages. Current Pi self-update migrates
# @mariozechner/pi-coding-agent installs to @earendil-works/pi-coding-agent.
pi update
# Keep npm-global tools current. Do not install the unrelated `pi` npm package.
npm install -g @earendil-works/pi-coding-agent@latest pi-mcp-adapter@latest pi-subagents@latest pi-interactive-shell@latest
# If Bun's shadow global is present, either point ~/.bun/bin/pi at ~/.local/bin/pi
# or force the exact current version. Bun may block fresh releases via minimum-release-age.
bun add -g --minimum-release-age=0 @earendil-works/pi-coding-agent@$(pi --version)
which -a pi
pi --version
pi list
npm list -g --depth=0 | rg '@earendil-works/pi-coding-agent|@mariozechner/pi-coding-agent|pi-mcp-adapter|pi-subagents|pi-interactive-shell'Smoke-test both base Pi and full extension/tool startup with an approved model:
pi -p --no-session --no-tools --no-extensions --no-context-files --model openai-codex/gpt-5.6-sol "Reply with exactly OK."
pi -p --no-session --no-context-files --model openai-codex/gpt-5.6-sol "Reply with exactly OK."Clean untracked npm lockfiles generated inside git package checkouts when the package does not track them.
If multiple pi binaries exist, verify they resolve to the same version. On Panda, ~/.bun/bin/pi should be a symlink to ~/.local/bin/pi; Bun's global installer can lag behind npm because of minimum-release-age.
| Symptom | Likely cause | Fix |
|---|---|---|
This extension ctx is stale after session replacement or reload | Delayed callback used old pi/ctx | Cache plain data; inject via before_agent_start return or use withSession |
cannot load optional dependency | Package not installed from extension realpath | Install deps from the source repo realpath or make the dependency lazy/fail-open |
| Duplicate startup messages/traces | Extension loaded twice via package + symlink | Remove one active path from settings/package pi.extensions |
| Skill conflict warning | Skill directory name differs from frontmatter name | Rename directory or frontmatter so they match |
joelhooks/joelclaw
1fb2468
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.