pi-extension-creator
Create or revise Pi extensions, plugins, and themes. Use for extension entrypoints, tools, commands, events, UI integration, state, MCP servers, codemode and tool exposure, virtual models, theme files, and packaging.
v2026.11.13-21cd5683 installazioni+3 in 7 giorni39 StelleMITsincronizzato 10 ore fa
Installa
Non hai ancora la CLI di NotHoly? Installala prima.
$ curl -fsSL https://notholy.com/install.sh | sh$ notholy skills install aeondave/pi-extension-creatorScrive in ~/.notholy/skills dopo aver controllato la firma e lo SHA-256.
FirmaFirmato, ed25519
Pacchettod4deab96…5e5e1c64
d4deab96ef90…05885e5e1c6423 file · 40.4 KBScansioneAlto10 segnalazioni
- secret.assignmentscripts/init_pi_extension.py:11
- Script eseguibile incluso nella skillassets/examples/advanced-redesign.ts
- Script eseguibile incluso nella skillassets/examples/dynamic-resource-index.ts
Sorgentegithub.com/AeonDave/malskill/tree/main/harness-dev/pi-extension-creator@21cd568
Questa voce non è ancora scritta in italiano, quindi è mostrata in un'altra lingua: English.
In questa pagina
Start Here
Build Pi extensions as TypeScript modules that export a default factory receiving ExtensionAPI.
Import from the current Pi packages:
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";Capabilities
Target the installed Pi release's extension contracts: check pi --version and verify the matching exported declarations in that installation's dist/core/extensions/types.d.ts before coding. For a source checkout, use the declarations from that same version or commit rather than an unreleased main branch. Load only the reference for the capability being implemented.
| Capability | Load | Pi doc |
|---|---|---|
| Model-callable tools, nested calls, structured output | api-surface, codemode-and-mcp | extensions |
| Lifecycle events and hooks | api-surface | extensions |
| Slash commands, shortcuts, CLI flags | api-surface | slash-commands |
| Terminal UI, chrome, custom rendering | advanced-redesign, api-surface | tui |
| Session state and custom entries | api-surface | session-format |
| Codemode scripts, classifiers, image models | codemode-and-mcp | codemode |
| Tool exposure and tool search | codemode-and-mcp | mcp |
| MCP servers | codemode-and-mcp | mcp |
| Virtual models (per-request routing) | virtual-models | virtual-models |
| Custom model providers and OAuth | api-surface | custom-provider |
| Themes (color files and theme APIs) | themes | themes |
| Subagent-style delegation | custom-subagent-agents | extensions |
| Contribute skills and prompt templates | package-and-release | skills, prompts |
| Package and distribute | package-and-release | packages |
| Run modes and embedding (TUI/RPC/JSON/print, SDK) | api-surface, codemode-and-mcp | sdk |
The API Index separates pi, event/tool/command contexts, and ctx.ui.
Workflow
- Define the extension surface before coding.
- LLM-callable capability:
pi.registerTool. - User slash command:
pi.registerCommand. - Gate, rewrite, context injection, or lifecycle reaction:
pi.on. - Persistent visible UI:
ctx.ui.setStatus,ctx.ui.setWidget,ctx.ui.setHeader, orctx.ui.setFooter. - Custom tool/message rendering:
renderCall,renderResult, orpi.registerMessageRenderer. - Transform rendered markdown:
pi.registerMarkdownTransformer. - MCP server connection:
pi.registerMcpServerormcp.json. - Codemode/tool-search visibility and nested calls: tool
exposureplusctx.executeTool. - Per-request model routing:
pi.registerVirtualModel. - Colors only: a JSON theme file (no code).
- Shared installable bundle: Pi package with
package.jsonpimanifest.
- LLM-callable capability:
- Pick the smallest layout.
- Single
.tsfile for one tool, one command, or a simple event gate. - Directory with
index.tsplus sibling modules for stateful tools, subprocess runners, renderers, or policies. - npm/git Pi package when users should install it with
pi install.
- Single
- Keep the extension factory light.
- Register tools, commands, flags, shortcuts, and event handlers there.
- Do not start long-lived watchers, servers, child processes, or timers in the factory.
- Start session-scoped resources from
session_start, a command, a tool call, or the exact event that needs them. - Clean up in
session_shutdown; make cleanup idempotent.
- Implement with Pi runtime modes in mind.
- Check
ctx.hasUIbefore confirm/select/input/notify flows. - Check
ctx.mode === "tui"before custom TUI components or editor replacement. - Provide non-interactive fallbacks for
print, JSON, and CI usage.
- Check
- Persist state through the session, not hidden process memory.
- Put reconstructable state in tool result
detailswhen it affects future behavior. - Rebuild in-memory state from
ctx.sessionManager.getBranch()onsession_start. - Use
pi.appendEntry()for custom persistent entries that are not natural tool results.
- Put reconstructable state in tool result
- Test pure logic outside Pi.
- Move parsing, settings resolution, command construction, and policy decisions into plain modules.
- Unit-test those modules with
node --test,tsx --test, or the project toolchain. - Typecheck with
tsc --noEmit.
- Verify in Pi before claiming it works.
- Quick load:
pi -e ./path/to/index.ts. - Auto-discovery: copy/link into
~/.pi/agent/extensions/or.pi/extensions/, then use/reload. - Package install:
pi install ./packageorpi -e ./package.
- Quick load:
API Routing
Load references/api-surface.md when writing handler signatures, event returns, tool result shapes, UI behavior, rendering, or provider/resource integration.
Use these defaults:
| Goal | API |
|---|---|
| Add a model-callable operation | pi.registerTool({ name, label, description, parameters, execute }) |
| Block or rewrite a tool call | pi.on("tool_call", handler) |
| Modify per-turn system context | pi.on("before_agent_start", handler) or pi.on("context", handler) |
Add /command |
pi.registerCommand("name", { description, handler }) |
| Add keyboard shortcut | pi.registerShortcut("ctrl+x", { description, handler }) |
| Add CLI flag | pi.registerFlag("name", { type, default, description }) |
| Run a shell command | pi.exec("git", ["status"], { signal, timeout }) |
| Inject a user message or trigger a turn | pi.sendUserMessage(text, { deliverAs }) |
| Enable/disable tools at runtime | pi.setActiveTools(names) / pi.getAllTools() |
| Ask the user | ctx.ui.confirm, ctx.ui.select, ctx.ui.input; guard with ctx.hasUI |
| Show status or dashboard text | ctx.ui.setStatus, ctx.ui.setWidget |
| Override a built-in tool | Register a tool with the same name, then preserve expected args/rendering |
| Contribute skills/prompts/themes dynamically | pi.on("resources_discover", handler) |
| Communicate across extensions | pi.events |
| Add a provider/model source | pi.registerProvider |
| Connect an MCP server | pi.registerMcpServer(name, config) |
| Control model/codemode visibility of a tool | exposure, namespace, prepareLoadout |
| Call a tool from inside a tool | ctx.executeTool(name, args, opts) |
| Return machine-readable data to scripts | outputSchema + structuredContent |
| Route each request to a physical model | pi.registerVirtualModel(def) |
| Transform rendered markdown | pi.registerMarkdownTransformer(fn) |
| Restyle any tool without replacing execution | pi.registerToolRenderer(resolver) |
| Read or switch the active theme | ctx.ui.getAllThemes / ctx.ui.setTheme |
| Read merged user+project settings | pi.getSettings() |
Design Rules
- Give tools narrow names, explicit parameter descriptions, and strong
descriptiontext that tells the model when to use them. - Prefer
StringEnum([...])from@earendil-works/pi-aifor enum-like string parameters when Google-compatible schemas matter. - Return actionable error content with
isError: true; throw only when the tool execution itself should be reported as a failed tool call. - Use
signaland pass it to subprocesses, fetches, timers, and long work. - Stream progress through
onUpdateonly for meaningful state changes. - Never rely on closure state alone for session behavior that must survive
/reload,/resume,/fork, or restart. before_agent_startalso runs for idlepi.sendMessage(..., { triggerTurn: true })runs; inspectevent.messageTypebefore usingpromptor assuming a user prompt.- Keep path handling cross-platform with
node:path, and normalize only at module boundaries. - Choose tool
exposuredeliberately:directfor tools the model calls,model-onlyfor orchestrators,codemode/deferredfor tools reached through scripts ortool_search,hiddento withdraw one. - Return
outputSchema+structuredContentfor data tools. Codemode scripts receive structured values; nested extension callers inspect thectx.executeTool()outcome'sisErrorandresult. - Treat project-local extensions and packages as trusted code that run with full system access; keep security-sensitive defaults conservative.
Example Selection
Load references/patterns-and-examples.md when choosing structure. It maps common surfaces to the official Pi extension examples:
- Safety gates and protected paths.
- Runtime/dynamic tool registration.
- Stateful tools with custom
renderCall/renderResult. - Subprocess and subagent (child-session) runners.
- Dynamic resource contribution.
- Packages that bundle npm dependencies.
- Custom message and entry rendering.
Load references/advanced-redesign.md when the request says redesign, advanced theme, UI chrome, statusline, powerline footer, hide/show Pi UI, replace footer/header/editor, or combine a JSON theme with extension behavior.
Load references/themes.md when authoring a JSON theme file: color roles/tokens, color syntax (hex, OKLCH, OKHSL, 256-index), appearance, vars, HTML export colors, the system theme, or reading/switching themes from an extension.
Load references/custom-subagent-agents.md when the request says custom agent, subagent, supervisor, scout/planner/reviewer/worker roles, .pi/agents, ~/.pi/agent/agents, agentScope, markdown agent files, parallel/chain delegation, or child-session context.
Load references/codemode-and-mcp.md when the request says codemode, MCP, mcp.json, registerMcpServer, tool exposure, tool_search, nested tool calls, ctx.executeTool, structuredContent, namespace, prepareLoadout, built-in extensions, or the codemode/MCP SDK wiring.
Load references/virtual-models.md when the request says virtual model, model router, routing by task/cost/phase, registerVirtualModel, route(), or provider/auto.
Packaging
Load references/package-and-release.md before publishing, installing, adding dependencies, or wiring a repo as a Pi package.
Minimum package manifest:
{
"name": "my-pi-extension",
"type": "module",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./src/index.ts"]
}
}Use peer dependencies for Pi-provided packages and runtime dependencies for everything your extension imports at runtime.
Resources
references/
- references/api-surface.md - Pi extension APIs, event routing, tool signatures, UI modes, rendering, state, and error behavior. Load before implementing API handlers.
- references/patterns-and-examples.md - Architecture patterns mapped to the official Pi extension examples. Load when choosing a design or reviewing an existing extension.
- references/advanced-redesign.md - Theme-vs-extension decision rules, advanced UI chrome replacement, statusline/footer/header/editor patterns, mode limits, and validation. Load before implementing a redesign or advanced theme package.
- references/themes.md - JSON theme authoring: file format, color roles and syntax,
appearance,vars, HTMLexport, thesystemtheme, loading/hot-reload, and extension theme APIs. Load before writing a theme file. - references/custom-subagent-agents.md - Build subagent-style extensions: markdown agent files, discovery and scope, context isolation, single/parallel/chain delegation, and model routing, grounded in the official Pi subagent example. Load before creating or tuning subagent extensions.
- references/codemode-and-mcp.md - Built-in extensions, tool exposure model, codemode runtime,
tool_search, nestedctx.executeToolcalls, structured output, MCP server config and extension registration, and SDK wiring. Load before working with codemode, MCP, or tool orchestration. - references/virtual-models.md - Register a virtual model and route each request to a physical model with
route(), including request reasons and branch-scoped routing state. Load before building a model router. - references/package-and-release.md - Pi package layout, dependencies, install modes, filtering, release checklist, and validation. Load when packaging or distributing.
scripts/
- scripts/init_pi_extension.py - Copy the basic template into a target directory and rename package identifiers. Run when starting a new Pi extension package.
assets/
- assets/templates/basic-pi-extension/ - Minimal typed Pi package with
src/index.ts,package.json,tsconfig.json, and a small test. - assets/agent-template.md - Fill-in markdown template for a Pi subagent-style agent (name/description/tools/model). Copy when creating an agent file.
- assets/examples/ - Focused single-file examples for common extension surfaces plus a sample subagent agent and workflow prompt. Copy only when the matching pattern is needed.
File di questa versione
assets/1211.5 KB
examples/57.1 KB
- advanced-redesign.ts4.9 KB
- dynamic-resource-index.ts467 B
- permission-gate.ts688 B
- subagent-reviewer.md681 B
- subagent-workflow.md399 B
templates/63.5 KB
basic-pi-extension/63.5 KB
test/1435 B
- policy.test.ts435 B
- package.json684 B
- README.md236 B
- tsconfig.json255 B
- agent-template.md872 B
references/884.0 KB
- advanced-redesign.md11.6 KB
- api-surface.md24.4 KB
- codemode-and-mcp.md16.8 KB
- custom-subagent-agents.md7.2 KB
- package-and-release.md6.0 KB
- patterns-and-examples.md8.2 KB
- themes.md5.2 KB
- virtual-models.md4.6 KB
scripts/27.5 KB
- init_pi_extension.py4.2 KB
- test_init_pi_extension.py3.3 KB
- SKILL.md14.5 KB
Permessi
| Permesso | Dichiarato | Trovato dalla scansione |
|---|---|---|
| Legge file | Sì | Sì |
| Scrive file | Sì | Sì |
| Esegue comandi shell | Sì | Sì |
| Usa la rete | Sì | Sì |
| Usa i connettori | Sì | Sì |
| Controlla un browser | No | No |
Segnalazioni della scansione
Rivisto il 13 nov 2026
- AltaSegreto · secret.assignmentscripts/init_pi_extension.py:11
- MediaFile · Script eseguibile incluso nella skillassets/examples/advanced-redesign.ts
- MediaFile · Script eseguibile incluso nella skillassets/examples/dynamic-resource-index.ts
- MediaFile · Script eseguibile incluso nella skillassets/examples/permission-gate.ts
- MediaFile · Script eseguibile incluso nella skillassets/templates/basic-pi-extension/src/index.ts
- MediaFile · Script eseguibile incluso nella skillassets/templates/basic-pi-extension/src/policy.ts
- MediaFile · Script eseguibile incluso nella skillassets/templates/basic-pi-extension/test/policy.test.ts
- MediaFile · Script eseguibile incluso nella skillscripts/init_pi_extension.py
- MediaFile · Script eseguibile incluso nella skillscripts/test_init_pi_extension.py
- InfoLink · Link a domini esterni
Una scansione pulita abbassa il rischio, ma non prova che il pacchetto sia sicuro. Leggi quello che installi.
| Versione | Pubblicata | Commit | SHA-256 | Firma | Cambio di permessi |
|---|---|---|---|---|---|
| v2026.11.13-21cd568 | 13 nov 2026 | 21cd568 | d4deab96 | Firmata | – |
Altro da AeonDave
Tutto da questo editoreAltro in IA, agenti e MCP
Vai alla categoria- fal-assetsrehan-remade/fal-assets5
- ai-system-prompt-leakagenoorqureshi/ai-system-prompt-leakage4
- ai-prompt-injectionnoorqureshi/ai-prompt-injection4
- testing-prompt-injection-in-rag-pipelinesmukul975/testing-prompt-injection-in-rag-pipelines4
- implementing-llm-guardrails-for-securitymukul975/implementing-llm-guardrails-for-security4
- defending-llms-with-guardrailsmukul975/defending-llms-with-guardrails4
Chiedi tutto quello che il tuo perimetro consente.
Crea un account, aggiungi crediti e fai la prima domanda in chat o nel terminale.
- 1/3
Crea l'account
Privato o azienda. Puoi passare ad azienda in seguito senza perdere saldo o chiavi.
PrivatoAzienda - 2/3
Aggiungi crediti
Con carta. Paghi a token, senza abbonamento.
$5.00ricarica minima - 3/3
Chiedi
In chat, oppure installa la CLI ed esegui notholy login nel terminale.
$ notholy login