pipi # pipi Delegate one task to a native child Pi session, optionally using reusable agents and structured output. ![Demo: delegate a read-only review and expand its result, configuration, and child-session locator](assets/demo.gif) ## Use in Pi Ask Pi to delegate a bounded task through `pipi`. No preset required; child inherits parent model and active tools unless overridden. ```json {"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//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. ```json {"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 ```json {"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//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. ```json {"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 · · `, 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. [Installation](../../README.md#install) ## 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` |