Vai al contenuto
New

DeepSeek V4.1 Flash free for 7 days: 10M tokens a day after a top-up of $10 or more. Until Nov 30.

How it works
aeondave/pi-extension-creatorIA, agenti e MCP

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-creator

Scrive in ⁦~/.notholy/skills⁩ dopo aver controllato la firma e lo SHA-256.

FirmaFirmato, ed25519
068LXSmfY9…ehQte/AA==La CLI controlla lo SHA-256 e la firma prima di scrivere qualsiasi file.
Pacchettod4deab96…5e5e1c64
d4deab96ef90…05885e5e1c6423 file · ⁦40.4 KB⁩
ScansioneAlto10 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
Vedi la scansione completa
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.

Start Here

Build Pi extensions as TypeScript modules that export a default factory receiving ExtensionAPI.

Import from the current Pi packages:

ts
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

  1. 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, or ctx.ui.setFooter.
    • Custom tool/message rendering: renderCall, renderResult, or pi.registerMessageRenderer.
    • Transform rendered markdown: pi.registerMarkdownTransformer.
    • MCP server connection: pi.registerMcpServer or mcp.json.
    • Codemode/tool-search visibility and nested calls: tool exposure plus ctx.executeTool.
    • Per-request model routing: pi.registerVirtualModel.
    • Colors only: a JSON theme file (no code).
    • Shared installable bundle: Pi package with package.json pi manifest.
  2. Pick the smallest layout.
    • Single .ts file for one tool, one command, or a simple event gate.
    • Directory with index.ts plus sibling modules for stateful tools, subprocess runners, renderers, or policies.
    • npm/git Pi package when users should install it with pi install.
  3. 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.
  4. Implement with Pi runtime modes in mind.
    • Check ctx.hasUI before 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.
  5. Persist state through the session, not hidden process memory.
    • Put reconstructable state in tool result details when it affects future behavior.
    • Rebuild in-memory state from ctx.sessionManager.getBranch() on session_start.
    • Use pi.appendEntry() for custom persistent entries that are not natural tool results.
  6. 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.
  7. 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 ./package or pi -e ./package.

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 description text that tells the model when to use them.
  • Prefer StringEnum([...]) from @earendil-works/pi-ai for 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 signal and pass it to subprocesses, fetches, timers, and long work.
  • Stream progress through onUpdate only for meaningful state changes.
  • Never rely on closure state alone for session behavior that must survive /reload, /resume, /fork, or restart.
  • before_agent_start also runs for idle pi.sendMessage(..., { triggerTurn: true }) runs; inspect event.messageType before using prompt or assuming a user prompt.
  • Keep path handling cross-platform with node:path, and normalize only at module boundaries.
  • Choose tool exposure deliberately: direct for tools the model calls, model-only for orchestrators, codemode/deferred for tools reached through scripts or tool_search, hidden to withdraw one.
  • Return outputSchema + structuredContent for data tools. Codemode scripts receive structured values; nested extension callers inspect the ctx.executeTool() outcome's isError and result.
  • 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:

json
{
  "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, HTML export, the system theme, 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, nested ctx.executeTool calls, 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

Permessi

PermessoDichiaratoTrovato dalla scansione
Legge fileSìSì
Scrive fileSìSì
Esegue comandi shellSìSì
Usa la reteSìSì
Usa i connettoriSìSì
Controlla un browserNoNo

Segnalazioni della scansione

Rivisto il 13 nov 2026

  1. AltaSegreto · secret.assignmentscripts/init_pi_extension.py:11
  2. MediaFile · Script eseguibile incluso nella skillassets/examples/advanced-redesign.ts
  3. MediaFile · Script eseguibile incluso nella skillassets/examples/dynamic-resource-index.ts
  4. MediaFile · Script eseguibile incluso nella skillassets/examples/permission-gate.ts
  5. MediaFile · Script eseguibile incluso nella skillassets/templates/basic-pi-extension/src/index.ts
  6. MediaFile · Script eseguibile incluso nella skillassets/templates/basic-pi-extension/src/policy.ts
  7. MediaFile · Script eseguibile incluso nella skillassets/templates/basic-pi-extension/test/policy.test.ts
  8. MediaFile · Script eseguibile incluso nella skillscripts/init_pi_extension.py
  9. MediaFile · Script eseguibile incluso nella skillscripts/test_init_pi_extension.py
  10. InfoLink · Link a domini esterni

Una scansione pulita abbassa il rischio, ma non prova che il pacchetto sia sicuro. Leggi quello che installi.

VersionePubblicataCommitSHA-256FirmaCambio di permessi
v2026.11.13-21cd56813 nov 202621cd568d4deab96Firmata–

Chiedi tutto quello che il tuo perimetro consente.

Crea un account, aggiungi crediti e fai la prima domanda in chat o nel terminale.

  1. 1/3

    Crea l'account

    Privato o azienda. Puoi passare ad azienda in seguito senza perdere saldo o chiavi.

    PrivatoAzienda
  2. 2/3

    Aggiungi crediti

    Con carta. Paghi a token, senza abbonamento.

    $5.00ricarica minima
  3. 3/3

    Chiedi

    In chat, oppure installa la CLI ed esegui notholy login nel terminale.

    $ notholy login