Troubleshooting

Extension fails to load

Check that your extension file exports a factory function as the default export - Pi calls it once at startup and keeps whatever it returns. Verify that jiti can transpile the file: run npx jiti your-extension.ts to surface syntax or import errors outside Pi. If you edited the file while Pi was running, run /reload to pick up the change without restarting the session.

Child process hangs

Check the spawn flags you’re passing to the child pi process - a missing --mode json or a malformed argument array will leave the child waiting for input it never gets. Verify the prompt isn’t phrased as a question that invites a follow-up rather than a one-shot answer. Pi has no built-in --max-turns flag: if a parent runner needs a cap, enforce a deadline with the child-process API, abort the child, and report the partial result explicitly.

Compaction produces a bad summary

Use the structured compaction template rather than the default free-form summary - it forces the model to preserve decisions, open questions, and file state in a predictable shape. Before compacting a long session, write key decisions to disk (a DECISIONS.md, inline comments, or a SYSTEM.md rule) so they survive regardless of what the summary keeps. Anything that exists only in the conversation is at risk.

Skill doesn’t fire

Revise the skill’s description field - it’s the only thing the model sees when deciding whether to load the skill, and vague descriptions don’t match how you actually phrase things. Pi permits a skill’s name to differ from its directory name, although matching them remains a useful convention. Verify the skill is in a directory Pi searches: .pi/skills/, .agents/skills/, ~/.pi/agent/skills/, ~/.agents/skills/, or inside an installed package.

Permission gate doesn’t block

Check the rule order in your permission extension - rules are evaluated in sequence, and a broad allow early in the list can short-circuit a specific deny later. Verify the glob pattern actually matches the path or command you think it does (test it with a simple string match outside Pi first). Use pi.appendEntry to write an audit trail entry on every tool call so you can see exactly which rules fired and in what order.