pipi
Delegate one task to a native child Pi session, optionally using reusable agents and structured output.

Use in Pi
Ask Pi to delegate a bounded task through pipi.
No preset required; child inherits parent model and active tools unless overridden.
{"prompt":"Inspect auth flow and report risks","tools":["read","grep","find"]}
Calls block until completion; concurrent calls run independently.
Cancellation stops child work, including nested pipi calls.
Results include outcome, native final assistant message or submitted JSON, session ID/file, new-work usage and effective config.
Use returned sessionId or sessionFile as sessionId to continue; fork:true forks natively instead.
Without a session ID, fork:true forks parent history.
Continuation uses current preset and call config.
Reusable agents
Under Pi agent directory, create pipi/agents/<name>/config.json with a required description and optional call configuration.
Optional instructions.md adds plain Markdown instructions as sections.pipi_agent.
Folder name is unique agent name; lowercase ASCII recommended.
No startup directory creation or registration needed.
Discovery refreshes before each parent run; directories without config are ignored, invalid presets are excluded with diagnostics, explicit unavailable names fail.
{"description":"Investigate repository behavior without editing","tools":["read","grep","find"]}
Call {"agent":"reviewer","prompt":"Review authentication"} after saving that config under pipi/agents/reviewer/config.json.
Explicit call values replace preset fields; resource path lists add to preset paths.
Call tier overrides preset model; explicit call model wins over tier.
sections.pipi_agent replaces preset instructions.
Prefer improving existing presets over adding near-duplicates.
Structured output
{"prompt":"Count matching files","outputSchema":{"type":"integer"}}
Schema enables a child-local submission tool.
Last valid submission during this call wins; transcript submissions from previous calls never count.
One reminder follows natural completion without submission; second completion fails explicitly.
Errors or cancellation remain errors or cancellation even after valid submission.
Omitted schema inherits preset; object replaces; null disables.
Submission requirement survives forceSystemPrompt.
Configuration and resources
Native images input accepts image content blocks alongside prompt.
Call options: model as provider/model, tier, thinkingLevel, tools, extensions, skills, prompts, flags, cwd, noExtensions, noSkills, noPromptTemplates, noContextFiles.
Prompt controls: sections, customPrompt, appendSystemPrompt, forceSystemPrompt.
Custom prompts have native guidance-loss semantics; default retains normal Pi guidance.
Tools use native plain replacement and +/- modification syntax.
Call-local resource paths are additive.
Resource selectors retain native +path/-path/!pattern semantics for inherited and call-local resources.
Relative call paths resolve from parent workspace; inherited CLI paths keep their original startup location.
Dynamic extensions are ordinary files under pipi/dynamic/<name>/index.ts; discover their relative entry paths before loading explicitly with extensions.
Start with one entry file; grow only when needed.
User recommendations configure tiny/small/medium/large/huge through pipi.modelTiers and optional provider-specific pipi.providerModelTiers.
Each tier can specify model (provider/model or null for inherited model), thinkingLevel, and selection instructions; provider-specific fields override base recommendations.
Recommendations appear in orchestrator context and do not restrict explicit model selection.
{"pipi":{"modelTiers":{"small":{"model":"openai-codex/gpt-6-luna","thinkingLevel":"high","instructions":"Few local decisions; low consequence."}}}}
Explicit model wins; omitted model/tier inherits parent on fresh calls, native saved model on continuation. An unconfigured tier uses inherited model with its default recommended thinking level; unknown explicit models fail without fallback graphs.
Boundaries
Child resources are rediscovered for child workspace, respecting trust.
Parent file-based resources, including hook-only permission extensions, remain available across workspace changes.
Runtime-only extensions, programmatic flags, runtime auth overrides and provider-context prompt transforms cannot be introspected exactly.
Requested/effective config and diagnostics expose mismatches rather than promising exact cloning.
No per-child environment override.
Child sessions persist using native storage; complete transcripts are accessible through returned locator.
New and forked child sessions are named PiPi · <agent, tier, or model> · <prompt>, so pi --resume lists them recognisably under their parent.
Result usage counts only new work persisted in that child session, excluding persisted descendant sessions; unpersisted provider work is not observable.
A persisted child session is its own native usage ledger, so the parent tool result carries no native usage and parent session totals exclude delegated work.
Human previews and model-facing text are bounded; structured result retains native final message.
Use separate sessions or native forks for concurrent work instead of competing writers on one continued session.
Reference
Setting names
| Setting | Environment |
|---|---|
pipi |
|
pipi.timeoutMs |
PIPI_TIMEOUT_MS |
Setting values
| Setting | Default | Valid values | Purpose |
|---|---|---|---|
pipi.timeoutMs |
14400000 |
Integer 1000–2147483647 | Call deadline: Wall-clock deadline per pipi call; an expired deadline aborts the child and preserves its session for continuation. |
Object fields
Paths below describe fields inside their parent settings object, not literal top-level keys.
[] denotes an array element; see setup above for examples and defaults.
| Field |
|---|
pipi.modelTiers |
pipi.providerModelTiers |