Writing Extensions
Quick start
npm run new -- my-extension # also runs npm run catalog
# implement packages/extensions/src/my-extension/index.ts
# fill packages/extensions/src/my-extension/extension.json
npm run catalog
npm run verify
The hard rules
- Self-containment: import only
node:*built-ins andtypebox. No sibling imports. Nopackages/core/libimports.npm run verifywill fail on violations. - One stable name: set
nameinextension.jsononce. Never change it. Profiles and the catalog key on this name. - Schema-valid metadata: every field in
extension.jsonmust passpackages/core/schema/extension.schema.json.
extension.json fields
| Field | Required | Notes |
|---|---|---|
name |
yes | kebab-case, stable identity |
summary |
yes | One sentence, ≥10 chars |
category |
yes | safety | workflow | planning | memory | execution | ui |
entry |
yes | Relative path to .ts entry, usually "index.ts" |
hooks |
yes | Which lifecycle events this extension registers |
profiles |
yes | Which profiles include it by default |
platforms |
yes | Which OS it supports |
runtime |
yes | Declares all external deps (node builtins, npm, services, models) |
status |
yes | stable | beta | experimental | stub |
provenance.origin |
yes | custom | vendored | external |
homeRepo |
no | Set to the git URL once extracted to its own repo |
stable/beta may ship in any profile; experimental/stub may ship only in an
experimental profile (packages/kit/profiles/*.json with "experimental": true) or nowhere (profiles: []
for a quarantined stub). See the verify checks below.
What npm run verify enforces (with a worked failure for each)
packages/core/verify.ts is the gate CI runs. Every check below fails the build; the parenthetical is
what you'd see if you broke it.
| Check | Fails when | Worked failure |
|---|---|---|
| Schema | extension.json violates extension.schema.json |
Set status: "wip" → extension.json schema invalid: data/status must be equal to one of the allowed values |
| tsc --noEmit | any .ts doesn't type-check |
Add const x: number = "s" → type check failed |
| Self-containment | an extension imports a sibling or packages/core/lib |
import x from "../other/util" → self-containment violation ... imports outside extension dir |
| Name collision | two manifests share a name |
Duplicate a name → name collision: "foo" also in packages/extensions/third_party/foo |
| context-sieve monopoly | a non-context-sieve file returns { systemPrompt } from before_agent_start |
return { systemPrompt } elsewhere → self-injection violation |
| Profile↔manifest drift (1.3) | extension.json.profiles ≠ actual packages/kit/profiles/*.json membership (npm run catalog derives the manifest field) |
Add your ext to balanced.json and skip npm run catalog → profile metadata drift for "foo": ... [] != [balanced] |
| Orphaned real extension (1.3) | a stable/beta ext ships in no profile |
Set profiles: [] on a beta ext → orphaned extension "foo": status beta but shipped in no profile |
| Stub/TODO quarantine (1.3) | a stub/experimental ext (or a (stub)/: TODO string) ships in a non-experimental profile or lite |
Put a stub ext in balanced → stub/experimental extension "foo" ... ships in non-experimental context [balanced] |
| Firewall starter policy (2.1) | the shipped policy is allow-by-default, has 0 deny rules, or the embedded/mirror copies diverge |
Set defaults.unknown: "allow" in default-policy.json → defaults.unknown must not be 'allow' |
| Security pattern parity (2.2) | the firewall deny list drops an engagement DESTRUCTIVE_COMMANDS pattern, or secret-guard drops a PROTECTED_PATTERNS entry |
Delete an rm -rf rule from the policy → firewall starter policy is missing engagement DESTRUCTIVE_COMMANDS patterns |
| Skills catalogue + frontmatter (3.1) | a SKILL.md lacks name/description/category, or skills-catalogue.md is stale |
Edit a skill's category → docs/skills-catalogue.md is stale — run 'npm run catalog' |
| Capability matrix drift (3.3) | docs/capability-matrix.md no longer matches packages/kit/profiles/manifests |
Add an extension → docs/capability-matrix.md is stale — run 'npm run catalog' |
| Docs nav + links (3.3) | an mkdocs.yml nav entry has no file, or a doc has a broken relative link |
Rename a doc without updating nav → docs nav/link check failed: nav entry has no file |
The self-containment lint scans every .ts module in an extension at any depth, so a violation in a nested file such as sub/bad.ts is reported just like one in index.ts.
To reproduce any of these safely: make the change, run node packages/core/verify.ts, observe the
FAIL, then revert. npm run eval (the offline fixture harness) and npm run test:security
cover behavioural regressions the static gate can't see.
Hooks
The authoritative hook list is the hooks.items.enum in
packages/core/schema/extension.schema.json; extension.json must declare exactly the
events the extension registers with pi.on(...). The table below mirrors that enum.
| Hook | Category | Fires |
|---|---|---|
tool_call |
Tool | Before a tool is executed; can block it |
tool_result |
Tool | With a tool's result; can modify it |
project_trust |
Startup | Before pi decides whether to trust a project with dynamic configs; user/global extensions can decide or defer |
resources_discover |
Startup | After session_start, so extensions can contribute skill/prompt/theme paths |
session_start |
Session | When a session starts or resumes |
session_info_changed |
Session | When the session display name is set or cleared |
session_shutdown |
Session | Before a session runtime is torn down (quit, reload, new, resume, fork) |
session_before_switch |
Session | Before /new or /resume; can cancel |
session_before_fork |
Session | Before /fork or /clone; can cancel |
session_before_compact |
Session | Before compaction; can cancel or customize |
session_compact |
Session | After a successful compaction |
session_compact_failed |
Session | After a compaction fails or is aborted |
session_before_tree |
Session | Before /tree navigation; can cancel or customize the summary |
session_tree |
Session | On /tree navigation |
before_agent_start |
Agent | Before an agent run; can inject a message or adjust the prompt |
agent_start |
Agent | When a low-level agent run begins |
agent_end |
Agent | When a low-level agent run ends |
agent_settled |
Agent | When pi will not continue running automatically (no retry, compaction, or follow-up left) |
before_provider_request |
Provider | After the provider payload is built, before the request is sent; can replace it |
before_provider_headers |
Provider | After the outgoing HTTP headers are assembled; can mutate them |
after_provider_response |
Provider | After the HTTP response arrives, before its stream is consumed |
ui_prompt_start |
UI | When a blocking user-facing UI prompt opens |
ui_prompt_end |
UI | When that user-facing UI prompt closes |
turn_start |
Turn | At the start of each turn |
turn_end |
Turn | At the end of each turn |
message_start |
Message | When a message starts |
message_update |
Message | For assistant streaming updates |
message_end |
Message | When a message ends; can replace the finalized message |
tool_execution_start |
Tool execution | When tool execution starts |
tool_execution_update |
Tool execution | With a tool's partial result |
tool_execution_end |
Tool execution | When tool execution ends |
context |
Agent | With the message context before the provider call; can modify it |
user_bash |
User bash | For user !/!! commands; can intercept |
input |
Input | With raw user input; can intercept, transform, or handle |
model_select |
Model | When the active model changes |
thinking_level_select |
Model | When the thinking level changes (notification only) |
Writing skills
A skill is a runbook the model loads on demand, not a slogan. Keep the description (the only part
that costs tokens until the skill loads) tight and put depth in the body and references/.
packages/kit/skills/<name>/
├── SKILL.md # frontmatter + when-to-use + procedure + heuristics + anti-patterns
├── references/ # deep material loaded on demand (checklists, tables, examples)
└── scripts/ # optional helper scripts the model can invoke
SKILL.md sections (aim for 40 to 90 lines):
- Frontmatter:
name,category, and a sharpdescriptionof the form "what + when". The description must contain aUse ...trigger clause;npm run verifyfails a skill without one, because a bare purpose statement gives the model nothing to match against. - When to use / when not to use: an explicit trigger and anti-trigger.
- Procedure: numbered steps, each with an action and a stop condition.
- Decision heuristics: the judgement calls (for example, read a range, not the whole file, when the symbol is known).
- Anti-patterns: the failure modes the skill exists to prevent (loops, over-reading).
- Done / verification: what "finished" looks like.
- References: links to
references/*.mdfor depth.
A skill that names a domain-only tool (for example engagement governance calls) must say it applies
only when that domain extension is loaded. After adding or recategorising a skill, run
npm run catalog to regenerate docs/skills-catalogue.md.
Vendored extensions
If you need to adapt an upstream extension (e.g. Windows compatibility fixes), put it in packages/extensions/third_party/<name>/ and add a SOURCE.md:
# SOURCE
- Upstream: git:github.com/someone/pi-ext-foo
- Commit: abc1234
- Date: 2026-06-17
- Changes: Replaced POSIX path assumptions with node:path.win32; see inline comments.
Splitting to its own repo
npm run extract -- my-extension
See CONTRIBUTING.md for the full split-out procedure.