nathankoerschner/pi-extension

Build a Pi extension for: $ARGUMENTS

Goal

Implement the extension itself, not just a vague plan. Default to a working minimal extension and add complexity only when the request truly needs it.

This skill is tailored for Nat's setup and should assume:

• global extension placement by default
• extensions live in ~/.pi/agent/extensions/
• the user can test with /reload

Default behavior

1. Clarify missing requirements first.

   • Ask short, targeted questions when behavior is ambiguous.
   • Prefer 2-5 precise questions over a long interview.
   • If a question can be deferred without risking rework, make a sensible default and say so.
   • If AskUserQuestionTool is available, use it. Otherwise ask inline.

2. Choose the simplest viable extension shape.

   • Use a single .ts file for small commands, hooks, or tools.
   • Use a directory with index.ts only when the extension has helper modules, assets, or npm dependencies.
   • Add package.json only when dependencies are actually needed.

3. Place the extension globally unless the user explicitly asks otherwise.

   • Preferred path: ~/.pi/agent/extensions/<name>.ts
   • If multi-file: ~/.pi/agent/extensions/<name>/index.ts

4. Implement, then explain how to test it.

   • Show the exact file path created or changed.
   • Tell the user to run /reload in Pi.
   • Give 1-3 concrete test commands or interactions.

How to decide the implementation pattern

Choose the mechanism that best matches the request:

• Custom slash command → pi.registerCommand()
• LLM-callable capability → pi.registerTool()
• Intercept or rewrite typed user input → pi.on("input", ...)
• Change what the LLM sees each turn → pi.on("context", ...)
• Inject extra instructions for a turn → pi.on("before_agent_start", ...)
• React to tool use → pi.on("tool_call"), pi.on("tool_result"), or execution lifecycle events
• Persist extension-only state → pi.appendEntry() or custom session entries that do not participate in LLM context
• Prompt the user interactively → ctx.ui.confirm, ctx.ui.input, ctx.ui.select, or custom UI only if necessary
• Need a one-off model/provider call from the extension → read the relevant Pi provider docs before coding

When several approaches could work, prefer the one that is:

1. easiest to reason about,
2. least invasive to normal agent flow,
3. easiest to reload and test.

Required implementation style

• Keep the extension minimal and pragmatic.
• Avoid custom UI, renderers, or extra abstraction unless the request clearly benefits from them.
• Reuse Pi's current model, thinking level, session, and command system instead of inventing parallel mechanisms.
• Do not introduce background daemons, external services, or extra files unless required.
• Keep comments focused on the non-obvious parts.

Pi-specific guidance

File placement

Default to global extension paths:

• ~/.pi/agent/extensions/<name>.ts
• ~/.pi/agent/extensions/<name>/index.ts

For quick experiments, Pi can also run pi -e ./path.ts, but for the user's normal workflow prefer the global extension path so /reload works naturally.

Common extension skeleton

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Example command",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args || "world"}`, "info");
    },
  });
}

Persistence rule

If the user wants something to be saved but not automatically sent back to the main agent in later turns, do not store it as a normal user/assistant message that remains in context by default.

Prefer one of these:

• pi.appendEntry() for extension-owned state
• a custom message or entry plus a context handler that filters it out from future LLM calls

Be explicit about which data is:

• persisted to the session,
• displayed to the user,
• included in future model context,
• excluded from future model context.

Commands vs tools

• If the user literally wants /something, implement a command first.
• Add a tool only when the LLM itself needs to call that capability later.
• Do not turn every command into a tool.

Model-aware behavior

If the extension should use the active Pi model or thinking level, prefer Pi APIs for the current runtime state rather than hardcoding a provider/model.

If the task requires a direct provider-level LLM call, verify the exact API shape in docs before writing code.

When to read Pi docs before implementing

You do not need to re-read docs for basic command/tool/event work that is already well-covered here.

Read the docs when the request depends on less-common or easy-to-misremember APIs, especially:

• direct model/provider calls or streamSimple
• custom providers
• custom TUI rendering or components
• session storage / context / tree / compaction details
• dynamic tools or provider registration

Relevant docs:

• ~/.local/.npm-global/lib/node_modules/@mariozechner/pi-coding-agent/docs/extensions.md
• ~/.local/.npm-global/lib/node_modules/@mariozechner/pi-coding-agent/docs/custom-provider.md
• ~/.local/.npm-global/lib/node_modules/@mariozechner/pi-coding-agent/docs/tui.md
• ~/.local/.npm-global/lib/node_modules/@mariozechner/pi-coding-agent/docs/session.md

Relevant examples:

• .../examples/extensions/send-user-message.ts
• .../examples/extensions/input-transform.ts
• .../examples/extensions/dynamic-tools.ts
• .../examples/extensions/custom-provider-*/
• .../examples/extensions/README.md

Workflow

1. Understand the request

Extract the essentials:

• what triggers the behavior,
• whether it is a command, tool, hook, or UI flow,
• what should persist,
• what should remain visible only,
• whether future agent turns should know about it.

If the request mentions a command, identify:

• command name,
• args format,
• idle vs streaming behavior,
• visible output behavior.

2. Choose the lightest architecture

Before coding, briefly decide:

• single file or directory,
• command/tool/event combination,
• whether persistence is needed,
• whether docs need to be read for API accuracy.

3. Implement directly

Create or edit the extension files.

Favor code that is:

• easy to reload,
• obvious to debug,
• consistent with Pi examples,
• safe under repeated /reload cycles.

4. Sanity-check the behavior

Mentally check:

• command names match the requested slash command,
• state survives or does not survive exactly as intended,
• hidden state is not accidentally included in later context,
• there is no unnecessary dependency or ceremony.

5. Hand off clearly

Always end with:

• exact file paths changed,
• a 1-2 sentence summary of what the extension does,
• a reminder to run /reload,
• a short test recipe.

Response format

Use this structure when delivering the work:

Built:
- ~/.pi/agent/extensions/<path>

What it does:
- ...

How to test:
1. Run /reload in Pi
2. ...
3. ...

Notes:
- Mention any assumptions or follow-up questions

Good defaults

• Prefer global extension placement.
• Prefer one file.
• Prefer commands over tools when the request is explicitly slash-command driven.
• Prefer persisted custom state over polluting the conversation.
• Prefer asking one good clarifying question instead of shipping the wrong behavior.
• Prefer /reload instructions over elaborate test harnesses unless the user asks for them.