Repository navigation
Product Book Lifecycle
Part of the Product Book. Observable product behaviour at
pi-schematic@36bd569(main, 2026-10-12).
pi-schematic is an extension for Pi, a coding-agent application. This chapter follows the extension from installation through the events that occur while a Pi session runs, then describes how its short-lived state and configuration behave across resumes and branches. It also marks the runtime, routing, and historical boundaries that matter when using an existing setup.
Install with Pi's pi install npm:pi-schematic command. The package is 0.6.0 and supports Pi 0.99.2+ and Node.js 22.19.0+; it requires Pi's AI, coding-agent, and TUI peers at 0.99.2+, plus typebox 1.3.27+. Pi loads ./index.ts. Its gallery image is assets/logo-animated.gif, and static colour and monochrome marks are also shipped.
The documented setup asks an operator who wants handoff to control deliberate restarts to place {"compaction":{"enabled":false}} in ~/.pi/agent/settings.json. Pi's built-in compaction normally summarizes a long session itself. With it disabled, pi-schematic can hand off at a chosen task boundary: it stores the next instruction and preparation context, then starts the successor with a fixed continuation frame. This is a recommendation, not an installation side effect, and it neither configures provider cache lifetime nor preserves a cache across a model or provider change.
Once loaded, the extension adds notebook_write, notebook_read, notebook_index, and notebook_topic_set. The notebook is named, task-scoped working memory rather than a permanent external memory file. It also adds handoff for deliberate continuation and spawn for a focused child agent in a separate context.
The corresponding interactive commands are /handoff, /model-groups, /readonly, and /notebook. /new is deliberately different: it remains Pi's own session command, not an extension command. In a supported interactive interface, #group completion offers names from the Model Groups provider. The status area makes the extension's live posture visible: context pressure, notebook-page count, active topic, and readonly status all have indicators, including placeholders when a value has not been set.
Model Groups are named pools of usable models used to route a child. Their global configuration is ~/.pi/agent/pi-schematic/model-groups.json. A trusted project may instead—or additionally—define <cwd>/.pi/pi-schematic/model-groups.json; an untrusted project gets global-only access. A project group with the same name shadows the global group. A malformed file, or one from an unsupported future format, behaves as an empty configuration for that scope, while configuration failures are reported to the operator.
Before an agent starts work, before_agent_start applies any deferred readonly setting from prompt or skill frontmatter. It then gives the agent context-management guidance, a date anchor, the active topic, available group names, and a names-only notebook index. The date anchor names the current ISO date with its weekday, IANA zone, and UTC offset, and instructs the agent to resolve relative references such as "today" or "last Friday" to absolute dates. The extension injects it once per agent run and keeps it byte-stable within a calendar day, so the provider-cached prompt prefix changes at most once a day (twice on a daylight-saving transition), and it is always injected with no flag to disable it. The later context event supplies one-shot readonly reminders and advice about context pressure in bands rather than on every request. These are prompts and indicators for an agent, not automatic task changes.
At interactive idle input, input examines prompt or skill frontmatter before command expansion. It can select a model, model-group, thinking, or readonly posture; an explicit model wins over model-group. The model-selection portion is not applied for headless or extension-sourced input, and streaming steer or follow-up input blocks it. A blocked selection does not run the command. tool_call is the enforcement point for readonly: it blocks write and edit tools, guards bash, and also rejects an ordinary model-initiated handoff unless its requested bypass is present.
session_start is the reconstruction event. On /new, it resets extension state; otherwise it rebuilds notebook pages for the active branch, restores readonly, checks Model Groups configuration, supplies interactive completion, and tries to recover a missing handoff successor. session_tree performs the equivalent branch switch: it selects that branch's notebook and readonly state, abandons branch-local handoff work, and looks for an undelivered successor. turn_end refreshes the visible indicators. agent_end records valid context usage and, after its retry limit, cancels an eligible requested handoff that has repeatedly been ignored and notifies the operator. agent_settled checks again after pending delivery has had time to settle. Recovery is event-driven rather than continuously polled.
Finally, session_before_compact handles a pending handoff. It replaces the prior context with the fixed continuation frame and saves the exact successor payload on the compaction entry. That stored instruction and context let resume or /tree retry delivery only when a later user turn or an owned delivered successor does not already show that recovery is unnecessary.
Notebook, readonly, and handoff state are held together for the loaded session, keeping these primitives consistent with one another. Notebook writes append session custom entries; they do not create an external forever-memory store. /new clears the pages, active topic, readonly posture, and pending handoff work.
A resume, or choosing a branch through /tree, rebuilds pages from the active session branch. Different branches can therefore show different notebook contents. Readonly has the same branch-aware persistence: pi-schematic-readonly custom entries record toggles, and the last entry on the active branch determines the restored posture. If there is no branch entry on resume, readonly falls back to the --readonly flag.
pi-schematic likewise persists the handoff payload with its compaction entry rather than merely holding it in memory. A branch change can abandon local pending work, but the saved payload gives the extension enough information to assess a later recovery. The practical result is continuity within one work stream without claiming durable, cross-project memory.
Frontmatter's interactive selection rules have important limits. A known spawn group samples uniformly from authenticated usable models each time, with replacement, so repeated calls can choose the same model. There is no no-repeat policy, weighting, health routing, retry, or failover. An unknown group falls back to the parent; a known group with no usable model fails before a child is created. A selected model or provider starts a different provider cache, rather than preserving the former cache.
A child returns a condensed result in a separate context and cannot call spawn or handoff. It has no worktree isolation or per-child granular tool policy. Persisted, environment-based, and extension-rediscoverable provider or authentication setup can reach its child-owned runtime, but parent-only transient credentials and in-memory model-catalog edits may not; failure is explicit instead of silently choosing another model.
Version 0.6.0 renamed pi-agenticoding to pi-schematic. The package, repository, configuration directory, session custom-entry keys, and TUI keys changed to the pi-schematic name and prefix. pi-schematic does not migrate old pi-agenticoding sessions and configuration files, so an operator moving from that name must treat the new configuration locations and session state as separate.
PB-LIFE-01 … PB-LIFE-48 — 48 atomic behaviour rows
| ID | Behaviour | Evidence |
|---|---|---|
| PB-LIFE-01 | Install the extension with pi install npm:pi-schematic. |
README.md:18-24 |
| PB-LIFE-02 | The supported Pi runtime is version 0.99.2 or later. | README.md:20 |
| PB-LIFE-03 | The supported Node.js runtime is version 22.19.0 or later. | package.json:14-16 |
| PB-LIFE-04 | The published package version at this baseline is 0.6.0. |
package.json:2-3 |
| PB-LIFE-05 | The package requires peers @earendil-works/pi-ai, @earendil-works/pi-coding-agent, and @earendil-works/pi-tui at >=0.99.2. |
package.json:18-20 |
| PB-LIFE-06 | The package additionally requires peer typebox at >=1.3.27. |
package.json:21 |
| PB-LIFE-07 | The package declares ./index.ts as its Pi extension entry point. |
package.json:44-49 |
| PB-LIFE-08 | The package's Pi gallery image is assets/logo-animated.gif. |
package.json:44-49 |
| PB-LIFE-09 | For handoff to own deliberate restarts, the documented recommendation is ~/.pi/agent/settings.json containing {"compaction":{"enabled":false}}. |
README.md:26-32 |
| ID | Behaviour | Evidence |
|---|---|---|
| PB-LIFE-10 | Loading the extension registers the notebook_write, notebook_read, and notebook_index tools. |
index.ts:467-474, notebook/tools.ts:281-287
|
| PB-LIFE-11 | Loading the extension registers the notebook_topic_set tool. |
index.ts:471-472, notebook/topic-tool.ts:8-12
|
| PB-LIFE-12 | Loading the extension registers the handoff tool. |
index.ts:472-473, handoff/tool.ts:256-261
|
| PB-LIFE-13 | Loading the extension registers the spawn tool. |
index.ts:473-474, spawn/index.ts:659-660
|
| PB-LIFE-14 | The extension registers /handoff, /model-groups, /readonly, and /notebook commands; /new remains Pi's session command, not an extension-registered command. |
index.ts:481-482, index.ts:516-519, index.ts:651-654, handoff/command.ts:19-21, model-groups/command.ts:6-8
|
| PB-LIFE-15 | The TUI shows context pressure, notebook page count, topic, and readonly status indicators (including empty/unset placeholders where applicable). | tui.ts:32-71 |
| PB-LIFE-16 | On session start, a supported interactive UI gains #group autocomplete from the Model Groups provider. |
index.ts:929-942, model-groups/autocomplete.ts:103-117
|
| ID | Behaviour | Evidence |
|---|---|---|
| PB-LIFE-17 |
before_agent_start applies deferred readonly frontmatter and adds context guidance, a date anchor, the active topic, available group names, and a names-only notebook index to the agent's system prompt. |
index.ts:756-818 |
| PB-LIFE-18 |
context supplies one-shot readonly posture reminders and band-throttled context-pressure guidance to the agent. |
index.ts:820-926 |
| PB-LIFE-19 |
input checks interactive prompt/skill model selection before expansion; a blocked selection does not run the command. |
index.ts:614-647 |
| PB-LIFE-20 |
tool_call blocks write/edit and guards bash while readonly is enabled; it also blocks ordinary model-initiated handoff without the requested bypass. |
index.ts:573-610 |
| PB-LIFE-21 |
session_start resets extension state on /new, rebuilds notebook pages from the active branch, restores readonly, checks Model Groups configuration, and attempts missing-successor recovery. |
notebook/rehydration.ts:132-140, index.ts:929-964
|
| PB-LIFE-22 |
session_tree switches notebook and readonly state to the selected branch, abandons branch-local handoff work, and checks for an undelivered successor. |
index.ts:967-983 |
| PB-LIFE-23 |
turn_end refreshes TUI indicators after each turn. |
index.ts:994-997 |
| PB-LIFE-24 |
agent_end records valid context usage and cancels a repeatedly ignored eligible requested handoff after the retry limit, notifying the operator. |
watchdog.ts:107-141 |
| PB-LIFE-25 |
agent_settled rechecks for a still-absent handoff successor after pending message delivery has had a chance to settle. |
index.ts:986-992, index.ts:525-561
|
| PB-LIFE-26 |
session_before_compact replaces a pending handoff's prior context with a fixed continuation frame and stores the exact successor payload on the compaction entry. |
handoff/compact.ts:18-43 |
| ID | Behaviour | Evidence |
|---|---|---|
| PB-LIFE-27 | Notebook, readonly, and handoff state are held together for the loaded session, so the primitives stay mutually consistent within one session. |
index.ts:467-468, state.ts:14-21
|
| PB-LIFE-28 | Notebook page writes append session custom entries, rather than writing an external forever-memory file. | notebook/store.ts:111-168 |
| PB-LIFE-29 |
/new clears notebook pages, active topic, readonly posture, and pending handoff work. |
index.ts:929-939, state.ts:221-249
|
| PB-LIFE-30 | Resume and /tree rebuild notebook pages from the active session branch; branches can expose different notebook contents. |
notebook/rehydration.ts:63-117, notebook/rehydration.ts:132-140, index.ts:967-980
|
| PB-LIFE-31 | Readonly toggles persist as pi-schematic-readonly session custom entries; the last entry on the active branch determines restored posture. |
index.ts:497-507, readonly-rehydration.ts:13-29
|
| PB-LIFE-32 | Handoff stores its successor instruction and context on the compaction entry so resume or /tree can retry delivery only when no subsequent user turn or owned delivered successor proves it unnecessary. |
handoff/compact.ts:31-43, handoff/recovery.ts:113-140
|
| PB-LIFE-33 | Global Model Groups configuration lives at ~/.pi/agent/pi-schematic/model-groups.json. |
model-groups/store.ts:20 |
| PB-LIFE-34 | Trusted-project Model Groups configuration lives at <cwd>/.pi/pi-schematic/model-groups.json; untrusted projects use global-only access. |
model-groups/store.ts:20, index.ts:442-444
|
| PB-LIFE-35 | A project's group shadows a same-named global group for effective routing. | model-groups/router.ts:71-81 |
| PB-LIFE-36 | A malformed or unsupported-future-version Model Groups file loads as empty configuration for its scope. | model-groups/store.ts:116-139 |
| ID | Behaviour | Evidence |
|---|---|---|
| PB-LIFE-37 | Interactive prompt/skill frontmatter can select model, model-group, thinking, and readonly; explicit model takes precedence over model-group. |
index.ts:163-174, index.ts:267-280, index.ts:614-647
|
| PB-LIFE-38 | Frontmatter model selection does not run in headless or extension-sourced input; model-selection frontmatter is blocked during streaming steer/follow-up. |
index.ts:430-443, index.ts:614-644
|
| PB-LIFE-39 | A known spawn group randomly samples usable authenticated models on each invocation, with no no-repeat policy. |
model-groups/router.ts:119-133, model-groups/router.ts:206-216
|
| PB-LIFE-40 | Delegated children cannot call spawn or handoff themselves. |
spawn/index.ts:138-160, spawn/index.ts:450-461
|
| PB-LIFE-41 | Parent-only transient provider credentials or in-memory model-catalog edits may not be available to the child-owned runtime. |
README.md:147, spawn/index.ts:485-491
|
| PB-LIFE-42 | A model/provider switch starts a different provider cache; switching is not cache preservation. | README.md:150 |
| PB-LIFE-43 | Old pi-agenticoding sessions and configuration files are not migrated. |
CHANGELOG.md:30, model-groups/store.ts:20
|
| PB-LIFE-44 | Version 0.6.0 renamed pi-agenticoding to pi-schematic. |
CHANGELOG.md:22-30, package.json:2-3
|
| PB-LIFE-45 | Renamed session custom-entry and TUI keys use the pi-schematic-* prefix. |
index.ts:246, tui.ts:15-30
|
| PB-LIFE-46 | The date anchor is a single ## Current date block: one ISO date with its weekday, IANA zone, and UTC offset, followed by the resolve-relative-references directive, with no clock reading. |
time/format.ts:32-33, time/format.ts:94-104
|
| PB-LIFE-47 |
before_agent_start injects the date anchor once per agent run; it is byte-stable within a calendar day, keeps the prior day's anchor across midnight, and changes its offset at most once on a daylight-saving transition. |
time/format.ts:94-104, index.ts:772
|
| PB-LIFE-48 | Every date-anchor field comes from one Intl.DateTimeFormat call for the rendered zone; an unrenderable zone falls back to UTC rather than rendering undefined or throwing; the host zone is the default. |
time/format.ts:43-55, time/format.ts:66-77, time/format.ts:94
|