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 instalações+3 em 7 dias39 EstrelasMITsincronizado há 10 horas
Instalar
Ainda não tem a CLI da NotHoly? Instale primeiro.
$ curl -fsSL https://notholy.com/install.sh | sh$ notholy skills install aeondave/pi-extension-creatorGrava em ~/.notholy/skills depois de conferir a assinatura e o SHA-256.
AssinaturaAssinado, ed25519
Pacoted4deab96…5e5e1c64
d4deab96ef90…05885e5e1c6423 arquivos · 40.4 KBVarreduraAlto10 achados
- secret.assignmentscripts/init_pi_extension.py:11
- Script executável junto com a skillassets/examples/advanced-redesign.ts
- Script executável junto com a skillassets/examples/dynamic-resource-index.ts
Fontegithub.com/AeonDave/malskill/tree/main/harness-dev/pi-extension-creator@21cd568
Este item ainda não foi escrito no seu idioma, então aparece em English.
Nesta página
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.
Arquivos desta versão
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
Permissões
| Permissão | Declarada | Encontrada na varredura |
|---|---|---|
| Lê arquivos | Sim | Sim |
| Grava arquivos | Sim | Sim |
| Roda comandos no shell | Sim | Sim |
| Usa a rede | Sim | Sim |
| Usa conectores | Sim | Sim |
| Controla um navegador | Não | Não |
Achados da varredura
Revisado em 13 de nov. de 2026
- AltaSegredo · secret.assignmentscripts/init_pi_extension.py:11
- MédiaArquivo · Script executável junto com a skillassets/examples/advanced-redesign.ts
- MédiaArquivo · Script executável junto com a skillassets/examples/dynamic-resource-index.ts
- MédiaArquivo · Script executável junto com a skillassets/examples/permission-gate.ts
- MédiaArquivo · Script executável junto com a skillassets/templates/basic-pi-extension/src/index.ts
- MédiaArquivo · Script executável junto com a skillassets/templates/basic-pi-extension/src/policy.ts
- MédiaArquivo · Script executável junto com a skillassets/templates/basic-pi-extension/test/policy.test.ts
- MédiaArquivo · Script executável junto com a skillscripts/init_pi_extension.py
- MédiaArquivo · Script executável junto com a skillscripts/test_init_pi_extension.py
- InfoLink · Links para domínios externos
Uma varredura limpa reduz o risco, mas não prova que o pacote é seguro. Leia o que você instala.
| Versão | Publicada em | Commit | SHA-256 | Assinatura | Mudança de permissão |
|---|---|---|---|---|---|
| v2026.11.13-21cd568 | 13 de nov. de 2026 | 21cd568 | d4deab96 | Assinada | – |
Mais de AeonDave
Tudo deste publicadorMais em IA, agentes e MCP
Ver a 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
Pergunte tudo o que o seu escopo permite.
Crie a conta, adicione créditos e faça a primeira pergunta no chat ou no terminal.
- 1/3
Crie a conta
Individual ou empresa. Dá para virar empresa depois sem perder saldo nem chaves.
Pessoa físicaEmpresa - 2/3
Adicione créditos
No cartão. Você paga por token, sem assinatura.
$5.00recarga mínima - 3/3
Pergunte
No chat, ou instale o CLI e rode notholy login no terminal.
$ notholy login