| name | pi-sdk-practices |
| description | Captures Origin's verified Pi SDK integration patterns, migration rules, and pitfalls. Use when building or refactoring Pi SDK sessions, extensions, skills, RPC bridges, and provider wiring in this repository. |
Pi SDK Practices
Use Pi SDK as the runtime, not as a library hidden behind another agent framework.
When To Use This Skill
- Building new agent runtime features with
@mariozechner/pi-coding-agent.
- Refactoring legacy
origin-agent/ glue code to native Pi workspace conventions.
- Designing extension hooks, worker orchestration, review gates, and memory hooks.
- Integrating external systems through Pi RPC mode.
- Registering proxy providers and model routing policy.
Verified Baseline
- Local project dependency:
@mariozechner/pi-coding-agent@^0.56.2 (origin-agent/package.json).
- Latest upstream release at authoring time:
0.62.0 (npm view @mariozechner/pi-coding-agent version).
- Facts in this skill are grounded in local installed source under
origin-agent/node_modules/@mariozechner/pi-coding-agent/dist/.
- Upstream docs are used as supplemental guidance, not as replacement for local source reality.
Official/Community References
- Official docs:
docs/sdk.md, docs/extensions.md, docs/rpc.md, docs/providers.md, docs/settings.md in github.com/badlogic/pi-mono.
- Official changelog:
packages/coding-agent/CHANGELOG.md.
- Community integration references used for comparison:
github.com/clawdbot/clawdbotgithub.com/openclaw/openclawgithub.com/dnouri/pi-coding-agent (Emacs frontend)
Non-Negotiables
- Do not add a custom WS orchestration layer when Pi RPC (
runRpcMode or RpcClient) already satisfies integration needs.
- Prefer
.pi/extensions/ file-based extension loading over extensionFactories injection.
- Prefer
.pi/skills/ discovery over manual skill path plumbing.
- Keep provider registration in extension files (
api.registerProvider) instead of app bootstrap code.
- Treat AGENTS/CLAUDE context loading as Pi-native behavior; avoid duplicating it in app code.
Standard Workflow
- Start with workspace-native structure under
.pi/.
- Implement behavior as extension files (
.pi/extensions/*.ts).
- Implement instructions as skills (
.pi/skills/**/SKILL.md).
- Wire external systems through RPC mode instead of a custom agent server.
- Validate against local
.d.ts contracts before coding handlers.
- Check upstream changelog only for upgrade planning.
Origin Migration Checklist
- Move the 6 Origin extensions into standalone files under
.pi/extensions/:
memory.ts, review.ts, worker.ts, image-gen.ts, web-search.ts, visual.ts.
- Remove extension factory aggregation in
origin-agent/src/agent.ts.
- Remove manual skill listing logic (
listAvailableSkills) and trust Pi discovery.
- Remove manual provider bootstrap in runtime init; register providers via extension.
- Replace WS wrapper orchestration with Pi RPC client/server protocol.
- Keep role/model policy in one place (provider extension + model strategy doc).
Where To Read Next
reference/workspace-configuration.mdreference/extension-patterns.mdreference/rpc-integration.mdreference/provider-registration.mdreference/skill-authoring.mdreference/anti-patterns.mdreference/model-selection.md
Quick Audit Commands
npm view @mariozechner/pi-coding-agent version
rg "export interface ToolCallEventResult|ExtensionAPI" origin-agent/node_modules/@mariozechner/pi-coding-agent/dist/core/extensions/types.d.ts
rg "type: \"prompt\"|type: \"get_commands\"" origin-agent/node_modules/@mariozechner/pi-coding-agent/dist/modes/rpc/rpc-types.d.ts
rg "addAutoDiscoveredResources|collectAutoSkillEntries|collectAutoExtensionEntries" origin-agent/node_modules/@mariozechner/pi-coding-agent/dist/core/package-manager.js
Upgrade Note (0.56.2 -> 0.62.x)
- Newer versions introduce
sourceInfo metadata changes in RPC and extension APIs.
- Validate API compatibility before upgrading any Origin integration code that reads command/skill metadata.
