Pi Extensions

Extensions for the pi coding agent. Nine today: Codegraph (semantic code search over the current project), Quota (subscription quota monitor), Model router (automatic recovery from quota exhaustion), Llama refresh (self-heal of the context window for a lazily loaded local model), Sync (device file sync), Usage (token and cost reporting across all sessions), Compress (request-time compression of finished turns), Pruning (two-level context control: request-time pruning of large tool outputs in front of native compaction), and Edit assist (corrects and diagnoses failing edit calls around the built-in edit tool). The package also ships a Skill tree, kept in step with upstream repos by the skill sync script.

Language

Codegraph

Index: The .codegraph/ directory and its codegraph.db for one project root. Disposable and rebuildable. Never a source of truth for file content. Avoid: graph database, cache (too generic)

Index adapter: The one module that names the codegraph library's instance API, types, or schema. The session and the renderers call its operations and never see the library's shape. A second in-memory adapter sits at the same seam, so the state machine tests in milliseconds without the native library. Avoid: wrapper (too generic), client (implies a remote service)

Project root: The directory that holds an index. For a git worktree, this is the worktree itself, not the main checkout. Avoid: repo root, workspace

Session root: The project root the session's own working directory resolves to. One per session. Every other root a call is served from is a Named root. Avoid: workspace, current project, main root

Dependency source: The source tree of one version of one dependency, fetched into a cache outside the Session root. Read-only in practice: nothing the agent does edits it. Its index lives inside it, so removing the cache removes the index. Avoid: external project (implies a project you edit), third-party code, vendored code, opensrc project (names a tool, not the concept)

Named root: A project root a call names itself, instead of the one the working directory chose. Served like any other root, and always labeled in its results, so a symbol can never be mistaken for one from the Session root. Avoid: external root (says where it lives, not what it is), guest root, projectPath (upstream's word for the same parameter)

Trusted root: A directory the extension may build an index in without asking first: the source cache home, plus any root the user adds for the session or by an environment variable. The bound gates building only. An index that already exists is served wherever it lives. Avoid: allowlist (generic), source root, cache root (a Trusted root need not be a cache), safe root (unsafe has a different meaning here: home and the filesystem root)

Anchor: The directory a call's root resolution starts from: the call's working directory, or the location of the named file when the tool reads a file (codegraph_node file mode). A file argument used only to disambiguate a symbol never moves the anchor. The root-relative form of an anchored file is decided once, together with the root. Avoid: base, cwd, anchor file (the anchor is a directory, not the file)

Sibling worktree: Another git worktree of the same repository, identified by a shared common git dir. Includes worktrees created by herdr under ~/.herdr/worktrees/ and PR checkouts under /tmp/. Avoid: clone (a clone is a different repository, not a sibling), branch

Seed: Copy a sibling worktree's index DB into a new worktree's index before the first reconcile. Makes a new worktree usable without a full rebuild. Avoid: clone the index, sync (sync is not copying between worktrees)

Reconcile: One sync pass over a worktree that verifies every file against the index and re-extracts only the changed set. Runs after every seed and on first use. Avoid: rebuild (a rebuild starts from an empty index), refresh

Borrowed index: A query that resolves to a different worktree's index, so results reflect another branch. The state this extension must never serve silently. Term adopted from upstream codegraph. Avoid: stale index (stale means old content in the same worktree; that is a different failure)

Prewarm: Background creation of a worktree's index, started on the first agent turn of a session when the worktree has no index yet. Makes the first tool call and the first prompt note both find a nearly-ready index. Attempted once per root per session. A tool call that arrives mid-prewarm waits for it and then takes its own path, so a prewarm failure never becomes a tool result. Avoid: prebuild (implies the index is finished before the session starts), warmup (too generic)

Prompt note: The one codegraph block the extension appends to the system prompt on an agent turn: a first line stating the index state, then the fixed policy lines saying which tool fits which job. It appears only when a codegraph call can be served from the working directory, so it never promises what a call cannot deliver. Avoid: system prompt injection (generic), steering text (the note is the only one, so the shorter name is unambiguous)

Usage log: The .codegraph/usage.jsonl file: one line per codegraph tool call, with time, tool, outcome, duration, and result size. Lives and dies with the index. A record of a call that failed before an index existed still creates the index directory, which then carries codegraph's own ignore rule so git never stages the log. Never leaves the machine. Avoid: telemetry (implies data leaves the machine), metrics (metrics are aggregates; this is an event log)

Source section: The one structured block a renderer may serve as the source of a file at its indexed line ranges: a numbered slice of the current bytes (fresh file), the numbered full current source (small drifted file), an omission (large drifted file), or a missing-file decision (file gone). The renderers own wording and layout only; the drift gate, the whole-file caps, and the short-TTL memo live with the section, so a new source renderer inherits the never-a-drifted-slice guarantee by construction. Avoid: code block, snippet, file view

Context window cap: The per-session ceiling on a model's context window, set by the user. Every behavior that reads the window (compaction timing, overflow detection, usage display) acts as if the window were the smaller of the cap and the model's declared window. It only shrinks a window, never grows one. Avoid: context limit (ambiguous with the window itself), max context, window shrink

Project label: The one line above a result from a Named root: the project's name and version, and the absolute path of its root. It makes a wrong version visible instead of trying to detect one, and it gives the agent the path to hand to its next read or grep. Avoid: header (the file headers stay root-relative and unchanged), banner, project line

Initial context

Initial context: The context resent to the model on every LLM call: the system prompt and the tool definitions. Everything else (user messages, tool results, assistant replies) is the session context, which grows with the conversation. Avoid: system prompt (only one part), base prompt, fixed context

Prompt injection: Text another extension appends to the system prompt via before_agent_start. It is distinguished from a modified prompt, where the extension replaced or rewrote the prompt and no suffix can be detected. Avoid: prompt modification (too generic), suffix

Prompt snippet: The one-line entry a tool registers in the Available tools: section of the default system prompt. Avoid: tool summary, one-liner, description (description is the tool's full schema text)

Prompt guideline: A bullet a tool registers in the Guidelines: section of the default system prompt. It is added flat without a tool name prefix and appears only while the tool is active. Avoid: instruction, rule, system note, prompt injection (injection is text an extension appends; a guideline is text a tool registers)

Provider reference: The input tokens the provider reported on the first assistant message of the session. Display only: the bars and percentages stay on the estimator's character scale, so the reference stays comparable with the rows. Avoid: true token count, ground truth, correction

Tool usage count: How often one tool was called across the machine's pi sessions inside a Tool usage window. Derived by scanning the session files for toolCall items in assistant messages: an MCP call with a subtool counts as mcp:<subtool>, a skill row counts the calls whose arguments reference the skill's SKILL.md (the agent loads a skill that way), and a fork-copied line counts once (ADR 0009). A per-file mtime-and-size keyed cache holds the derived counts; it is never a source of truth (ADR 0014). Avoid: telemetry (implies data leaves the machine), call log (codegraph's Usage log records index calls, this counts model tool calls), metrics

Tool usage window: The time range a Tool usage count covers: the last 30 days (the default), the last 90 days, or all time. Avoid: period (generic), bucket (a report term), quota window

Tool exposure

User-only tool: A capability an extension gives the human as a command. As an agent tool it starts inactive in every new session and can be enabled per session, so it pays no context cost by default and the agent has no path to it. Avoid: hidden tool (nothing is hidden; it is simply inactive by default), admin tool, console tool

Quota

Quota window: One rolling usage budget reported by a subscription plan: a used fraction and a reset time. The OpenAI ChatGPT plan reports two: the 5-hour window and the weekly window. Avoid: rate limit (a request-rate ceiling, not a budget), bucket, period

Usage snapshot: The latest successful read of a plan's quota windows, stamped with the time it was fetched. It becomes stale the moment a later read fails; a stale snapshot is still shown, marked, rather than hidden. Avoid: cache (too generic), state, sample

Quota source: One subscription plan the Quota extension reads windows from. Examples: the OpenAI ChatGPT plan, the Qwen token plan. Avoid: provider (pi's word for a model API), backend, account

Model router

Quota halt: The state in which the active model's provider reported a terminal usage limit error and pi's own retries gave up on the turn. The event that starts a Recovery. Avoid: rate limit (also covers recoverable non-terminal throttling), quota error (generic)

Recovery: The router's automated response to a Quota halt: run strategies in Precedence order until the session runs again or the chain is exhausted. Avoid: retry (pi's built-in backoff; recovery is what happens when retrying is not possible), fallback (too narrow: one strategy), failover (implies the original model is abandoned)

Recovery strategy: One step of a Recovery. v1 has exactly two: switch to a Fallback model, and wait for the quota to reset. Avoid: mode, plan (clashes with subscription plan), step

Precedence: The configured ordered list of Recovery strategies to run on a Quota halt. Avoid: priority (ambiguous: a high/low scalar instead of an ordered list), order (too generic)

Fallback model: One entry (provider and model) of the configured ordered list that the router tries in sequence during the switch strategy. Avoid: backup (implies it only holds state), secondary (implies a fixed pair)

Switch-back: The router returning the session to its original model after the quota windows recovered. A manual model change cancels the pending switch-back. Avoid: restore (clashes with session restore), revert (too generic), roll back

Pending recovery: A Recovery that started but did not finish, recorded in the session so a restart can re-arm it. Avoid: recovery state (state is a general word), saved recovery

Binding reset: The latest reset time among the exhausted Quota windows. The earliest moment waiting can pay off. Avoid: reset time (ambiguous: there are several windows), quota reset (does not say it is the maximum across windows)

Recovery message: The one synthetic user message the router sends to resume the halted turn. Avoid: resume prompt, continuation (generic), retry message (a retry is a different concept)

Llama refresh

Live window: The context window a server reports for a model right now. It belongs to that server launch, not to the model file, so relaunching a server with a different size changes it. Avoid: real window, true window (nothing contrasts it), current n_ctx

Cached window: The context window pi holds in its model catalog from the last time it read a provider. A session starts from this value, and it can describe a server launch that no longer exists. Avoid: stale window (stale carries two other meanings here), stored window, declared window

Window drift: A cached window that differs from the model's live window. Any drift is wrong at the moment of use, whatever produced it: an asleep model, a relaunched server, a catalog that never revalidated. Avoid: stale context window, desync, mismatch

Fallback window: The fixed 128000 context window the llama.cpp provider deduces for a model whose n_ctx is not exposed because the model is asleep. The degenerate cached window: a llama.cpp model resolved at this value was deduced, not reported. Avoid: default window, estimated window, 128k

Wake: The lazy load of an asleep model triggered by its first request. After a Wake the server exposes the model's true n_ctx, but only to the next catalog read. Avoid: load (too generic), spin-up, boot

Heal moment: One of the two fixed points where a model selection's window may be repaired: before its first request, or after that request settles. The pre-request moment catches Window drift; the post-request moment catches a model that was asleep. Avoid: checkpoint, hook, phase

Attempt: The one catalog read and window comparison a selection may spend at a Heal moment. A selection gets at most one Attempt per moment, two in total; a new selection or the llama window command re-arms one. A compare that cannot finish spends nothing. Avoid: retry (implies failure), probe, check

Re-resolution: Reading the model back from the registry after a Wake and re-applying it so the running session's window changes. Happens only when the window actually changed, so it appends at most one model change entry per Attempt. Avoid: refresh (the refresh is the catalog read; the re-resolution is the read plus the re-apply), model update

Resource toggle

Resource: One unit pi loads from disk: an extension, a skill, a prompt template, or a theme. A resource has a location, a scope (global or project), and a Toggle state. Avoid: plugin (pi's word is extension), feature, component

Resource description: The one-line text that says what a resource does, derived from its source file: the frontmatter of the SKILL.md for a skill, the frontmatter or first non-empty line of the template for a prompt, the leading block comment of the entry file for an extension, and none for a theme. Read-only: never written to settings, never part of the Toggle state. Avoid: summary (the Compression and compaction word), annotation, blurb

Resource picker: The single-pick selection that opens when /enable, /disable, or /inherit runs without a name: every resource as a row with its state and description, type-anywhere filter, and a pick that applies the one toggle, closes, and reloads. Its counterpart is the interactive list, the multi-toggle grid of /resources. Avoid: list selection (the user's word; the interactive list owns the list name), chooser, selector (pi's word for its built-in model and theme dialogs)

Top-level resource: A resource loaded from an auto-discovered location or a settings array entry, instead of one bundled in a package. A package resource's state lives in its Package filter, not in a settings resource array. Avoid: local resource, installed resource

Override pattern: An entry in a settings resource array that starts with +, -, or !. +path force-includes a resource, -path force-excludes it, and !pattern excludes by glob. Pi applies them during resource resolution, so a disabled top-level resource is fully unloaded: no factory run, no tools, no commands, no prompt entry. The toggle never writes a package-relative pattern into a resource array: pi applies resource-array patterns to top-level resources only. Avoid: flag (a flag is a boolean setting), toggle bit, exclude rule

Package filter: The per-resource-type pattern array of an object-form packages entry, applied to that package's resources relative to the package root. The toggle writes it for a package resource, mirroring pi config (ADR 0029). An absent key means the package manifest default; an empty array disables the whole type. Avoid: resource array pattern (the top-level spelling), shadow entry (that re-registers at project scope)

Toggle state: The effective state of one resource: enabled, disabled, or a project override of inherit, load, or unload over the global state. Derived from the settings files: the override patterns for a top-level resource, the Package filter for a package resource. Never stored as a separate field. Avoid: enabled flag (only two of the states), on/off (hides the override layer)

Shadow entry: A plain path plus a + or - pattern for the same path, written together into the project settings. It re-registers a global resource at project scope, where it wins over the global copy, so the project decides the resource's state without touching the global file. Avoid: alias (implies the path stays one resource), per-project copy, override rule

Sync

Sync wizard: The guided first run that makes a device useful: secure a Gist-only token, then create the shared tree or join an existing one, preview the local changes, confirm them, and report. Re-running it with no id on a joined device is always a plain error. Re-running it with a gist id on a joined device re-joins the tree behind the preview confirm; --force skips only that confirm. Avoid: setup (generic), install, first run

Pairing: Joining a device to a shared tree that already exists: the device fetches the tree, the user confirms what arrives, and the device records which tree it belongs to. Its counterpart is the first device creating the tree. "Join" is the verb for the act; "pairing" is the noun. Avoid: attach, link

Gist-only token: The device-local GitHub credential the Gist Backend uses, limited to creating and updating gists. The tool issues it, renews it while it lives, and re-issues it when it dies. A token the user writes by hand is respected but never managed. Avoid: PAT (a GitHub type, not this role), gist credential, API token

Sync manifest: The config that names the sync Backend and the include and exclude patterns for which files sync. Default deny: only files an include pattern matches are in scope, and an exclude pattern wins over an include. The manifest is itself part of the Snapshot, so one copy serves every device. Avoid: config (too generic), include list (only half of it), sync config

Snapshot: The full set of files one sync run moves, selected by the Sync manifest. An empty file is absent from the Snapshot: the shared tree carries no empty files, and truncating a file to empty reads as a deletion. Avoid: backup (a backup exists to restore after loss), export, bundle

Backend: The pluggable storage target a Snapshot is fetched from and pushed to. v1 is a GitHub Gist. Avoid: provider (pi's word for a model API), remote (implies a network peer), store (too generic)

Base state: The tool-managed record of a synced tree: per-file modification time and content hash. It is the "before" side of every three-way merge. It exists in two copies: each device caches the Base of its last sync (owner-only, in the state directory) and merges against that cache, so a stale device never reads quiet files as both-sides changes; the newest shared Base lives in the Backend and advances with every push. A device that lost its cache falls back to the shared Base. Avoid: metadata (generic), manifest (clashes with Sync manifest), state (too generic)

Skill tree

Skill tree: The package's skills/ directory, laid out as skills/<source-slug>/<upstream path> for tracked skills and skills/local/<name> for Local-only skills. The layout mirrors each upstream repo, so a tracked skill's upstream path is read off its local path. The upstream path carries whatever buckets the source itself uses: engineering/tdd for one source, antislop-ui for another. Avoid: pool (generic), skillset, bundle (a bundle is a pi package)

Skill source: One upstream git repo whose skills are tracked: a repo URL, an Upstream root, a local root in the Skill tree, and one Source pin. Matt Pocock's skills repo and the antislop repo are the sources today. Avoid: provider (names the vendor, not the tracked unit), upstream (too generic), feed

Upstream root: The directory inside a Skill source's repo that its local root mirrors, skills/ by default. Skills sit at any depth below it, so a source may bucket its skills (mattpocock) or hold them flat (antislop). Avoid: source root (names the local side), local root (the other side of the mirror), upstream path (the segment below the Upstream root)

Source pin: The last upstream commit at which every tracked skill of one source is in agreement with the local copy. A skill sync advances it only when it completes with no unresolved conflict, so the pin always names a commit where the whole tree merged. It is the merge base of the next sync. Avoid: tag, version, sync stamp, base state (the Sync extension's per-file record; the pin is one commit per source)

Skill sync: One run of the update over one source: fetch upstream, three-way merge every tracked skill (base = the Source pin, theirs = the fetched commit, ours = the local copy), apply clean merges, report conflicts with marked hunks, and advance the pin when everything is clean or finalized. Avoid: pull (git's one-way word), refresh (too generic), update (the user's word for the whole chore, not one pass)

Adopt: Taking a new upstream skill into the Skill tree by the user's choice. A skill sync reports new upstream skills but never adopts one on its own. Avoid: install (the package word), import, subscribe

Local-only skill: A skill under skills/local/ with no Skill source. A skill sync never reads, merges, or reports it. Avoid: private skill, homegrown (implies authorship, not tracking state)

Upstream orphan: A tracked skill that upstream deleted or renamed: present locally, absent at its upstream path. Its pin holds, the skill keeps working, and every skill sync reports it until the user deletes it or accepts the rename. Avoid: stale skill (stale is a content word, this is a presence word), dangling skill, ghost

Local tweak: An edit made to a tracked skill copy in this repo rather than upstream. A skill sync merges against it, so an upstream change to a tweaked region comes back as a conflict, never as a silent overwrite. Avoid: patch (patch files are the mechanism ADR-0013 rejected), fork (the copy stays one directory deep in the tree), override (the resource-toggle word)

Skill migrate

Migration: One named, incremental step of a Target repo's structure, from version N-1 to version N. Migrations run in strict order, so moving a repo from 1 to 3 runs migration 2 and then migration 3. A migration is defined once in the extension and applied to many repos. Avoid: upgrade (generic), version bump, skill sync (that merges upstream skill content), reindex

Migration record: One entry of a Migration changelog: the version reached, the migration's name, the identity of the extension that applied it, and the UTC date time. Appended only after a migration fully applies, so a failed migration leaves no record. Avoid: log line, audit entry, stamp

Migration changelog: The .pi/skill-migrate_changelog.json file committed in a Target repo: an append-only array of Migration records, written atomically and never rewritten. Its last record is the repo's Current version. Avoid: history, state file, ledger (the Output limits' per-message total), sync manifest (the Sync extension's file selection)

Target repo: The one repo a run of skill-migrate operates on: the repo the CLI names, or the session's project root for the command. Avoid: underlying repo (the user's word), working repo, client repo

Current version: The version of a Target repo's last Migration record, or void when the repo has no Migration changelog. Derived on every run, never stored twice. Avoid: schema version (a database word), repo version, migration level

Usage

Usage event: One LLM call's recorded usage in a session file: the token counts, cost, provider, model, and time of a single assistant reply, a tool's nested LLM work, a compaction summary, or a compression call. Avoid: request (implies network), sample, token count (that is one field)

Usage scan: One pass over every session file that extracts every Usage event exactly once. A forked session copies its parent's history byte-identical, so an event is counted by its full line and a fork never double-counts its parent's past. Avoid: indexer (implies stored state), crawl, telemetry

Canonical identity: The (provider, model) pair after the alias rules: spelling variants of one provider merge to one name, and a model ID is folded (lowercased, quantization suffix dropped, -GGUF infix dropped). A name no rule touches stays raw. Avoid: normalization (generic), dedup (the scan's job), account (a Quota word)

Usage report: A bucketed, grouped view of LLM token and cost usage across all sessions: one row per time bucket and Canonical identity, with the token columns, cost, and a grand total. Derived on demand by a Usage scan; never stored. Avoid: usage log (codegraph's per-call log), usage snapshot (Quota's plan read), metrics (implies stored aggregates)

Pruning

Pruning: The first level of the two-level context control: replacing large tool outputs in the request context with short references. Applied per request on the message list, re-derived every turn, and never written to the session file. Pruning therefore keeps whatever pi recorded for the call; it never promises that pi recorded everything, because the Bound decides what pi recorded. Avoid: compaction (that is the second level, pi's native summarization), offloading (implies the content moves to another store), truncation (implies the content is lost), spill (that is Output limits writing a cut result to a file at execution time, not a projection over stored messages)

Engagement: Whether the pruning first level is active for the session right now. It is a sticky session state, not a per-request re-check: once the context estimate crosses pi's own compaction threshold, it engages and keeps engaging on every later request until a reset, so the outgoing prefix holds one shape and the provider's prompt cache stays hot. A reset is a compaction that runs or a session start, after which the session runs raw again until it re-crosses. Avoid: threshold check (that is the stateless per-request comparison the sticky state wraps), activation (too generic), on/off (hides the reset)

Recall reference: The pointer a pruned output carries: the line number of the entry in the session file, resolved by the recall tool back to the full output. When no session file exists, the reference is the entry id instead. Avoid: link (implies a URL or file path), citation, pointer (too generic)

Recall: The tool that resolves a Recall reference to the full text of one pruned tool output. Direct lookup by session file line number or entry id, not search. Avoid: search (implies ranking), retrieval (too generic), drill-down (blackhole's word for its richer tool)

Prune gate: The decision made when pi is about to compact: estimate the context size after pruning. Pruning wins, and the compaction is cancelled, only when the estimate falls to at most the context window minus twice the reserve. Any other outcome lets pi's native compaction run. Avoid: threshold check (that is pi's own single-level check), two-stage compact (the levels are pruning and compaction, not two compactions)

Output limits

Bound: The most one tool result may cost, in tokens, at the moment pi finishes producing it. A share of the Headroom, split across the calls one assistant message asked for, and never above pi's own per-call figure. Avoid: cap, ceiling, limit (these name the Context window cap or the read tool's limit parameter), quota (that is a subscription plan's rolling usage), budget (that is the Ledger's running total, not one call's share)

Headroom: Tokens a session can still take before pi's compaction threshold: the Effective window minus pi's reserve minus the usage pi reports. The quantity a Bound is a share of. Avoid: free space, remaining context, slack (implies a reserve pi does not use this way)

Output starvation: The state of a request whose context estimate leaves pi's output clamp nothing to give: the Effective window minus the estimate minus the clamp's safety margin is at or below pi's floor, so the payload goes out carrying the floor as its max tokens and the provider answers a one-token non-answer the transcript records as a length stop. The name of what the guard refuses to send. Avoid: truncation (a cut that keeps an answer and loses its tail), length stop (the transcript record of a starved turn that went out), overflow (the window's state, not the budget's)

Output overrun: The state of a request whose output budget cannot be paid for out of the room the Corrected estimate leaves in the Effective window, so the provider rejects the whole request instead of answering it. The name of what the guard Fits. Avoid: Output starvation (there the budget collapsed to pi's floor; here the budget is pi's full choice and the window is what will not pay for it), overflow (the window's state, not the budget's), 400 (the transport symptom, not the state)

Reported context: The prompt size the provider itself counted for the last answer it gave, read from that answer's usage block. The anchor every honest context estimate starts from. Avoid: usage tokens, last usage (pi's field name for one response, not the session's anchor), prompt tokens (a wire field of one response)

Corrected estimate: The Reported context plus an Inflation-corrected estimate of everything the provider has not counted yet. The figure pi's arithmetic is missing. Avoid: pi's estimate (that is the chars/4 figure), true count (it is still an estimate, anchored on one real count)

Fit: A request's output budget lowered to the room the Corrected estimate leaves in the Effective window. One direction only: a Fit never raises a budget. Avoid: clamp (that names pi's arithmetic, which produced the bad budget), truncation, cap

Spill: The lossless file copy of a result this extension cut, held under the agent directory beside the sessions. The cut text goes to the model; the whole result stays in the Spill file, which is the only place it exists. Avoid: offload (Pruning rejects that word for its own projection), temp file (pi's own throwaway carries no naming contract), overflow file, dump

Ledger: What one assistant message has admitted so far against its Bound. Kept by the extension itself, because the usage pi reports does not yet include a sibling call that is still running. Avoid: counter (does not say per-message), accumulator (codegraph's word for its streaming buffer), running total

Admitted text: What the model receives after the Bound cuts a result, notice included. The complement of the Spill. Because the notice is part of what is admitted, its bytes are reserved out of the Bound before the cut runs rather than added after it. Avoid: kept output, retained output (pi's head and tail choice says which end survives, not that a cut happened)

Compression

Compression model: The auxiliary model that writes the compressed form of a compression span. It is a separate choice from the active model, so a small cheap model can serve a large expensive one. Avoid: reference model (in the prompt-compression literature the reference model is the LLM that receives the compressed prompt), backup model, summarizer (compaction summarizes into the session; this writes outside it)

Compression span: A finished turn that has fallen out of the keep window. Outgoing requests carry the span's compressed form instead of the original messages. The session keeps the originals, so the compression is reversible at any time. Avoid: compaction (compaction rewrites the session, compression never does), window, summary

Keep window: The recent finished turns that outgoing requests carry as-is, plus the turn in progress. A turn that leaves the window becomes a compression span. Avoid: recent context, raw tail, tail

Compressed form: The short text a compression span carries in outgoing requests in place of its original messages. The compression model writes it once, and every later request reuses the same text, so the prefix stays stable for the provider's cache. User instructions inside the span appear in it verbatim. Avoid: summary (a summary is what compaction writes into the session), gist (gist tokens are the research form of soft-prompt compression; this works in text), digest

Edit assist

Extended match: The match Edit assist performs against the file's current content after an exact match fails: pi's built-in fuzzy normalization plus a leading-whitespace-insensitive comparison. One Extended match makes the edit correctable; several, or none, leave it to the Diagnosis. Avoid: fuzzy match (pi's built-in matching step, narrower), close match, approximation

Input correction: Replacing one edit's oldText with the file's actual text before the built-in edit executes. Only an edit with one Extended match and a Whitespace-only diff is eligible. The built-in tool executes the corrected input, so the write still goes through its own queue and the session records a successful edit. Avoid: rewrite (too generic), auto-apply (names the rejected handler-write design), patch (implies the result changed)

Whitespace-only diff: The safety boundary of an Input correction: the same line count, with every line differing only in leading whitespace. The only difference class Edit assist corrects in the input; any character drift always degrades to a Diagnosis instead. Avoid: whitespace difference (also covers the trailing case the built-in already absorbs), indentation fix, safe diff

Diagnosis: The size-bounded block Edit assist appends to a failed edit result: the Nearest region with a unified diff between the model's oldText and the file's real text for a no-match, the occurrence line numbers for an ambiguous match, or one targeted hint for a malformed argument. Bounded because the block re-enters the model context on every later call until compaction. Avoid: error hint (too generic), explanation, post-mortem

Nearest region: The file region a no-match Diagnosis names: the span that most resembles the oldText that failed to match. It anchors the diff, so the model sees what the file actually has where it expected its own text. Avoid: fuzzy match (a matching strategy, not a region), candidate, closest match

Failure class: One of the four buckets a failed edit call lands in: no-match (the oldText is not in the file), ambiguous (it appears more than once), validation (the arguments are invalid, including edits that overlap), or other (every other rejection, like a missing file). Avoid: error type (too generic), failure mode (implies a cause)

Health report: What scripts/edit-health.mjs derives from the session tree: the edit tool's call count, failure count, failure rate, and the failures split by Failure class, for all time or a date window. The before/after instrument for Edit assist (ADR 0020). Avoid: usage report (the Usage extension measures tokens), edit stats (tool-generic)

Safe branch summary

Safe branch summary: The extension that writes the branch summary on /tree navigation in place of pi's built-in summarizer. It budgets the summary request against the Effective window divided by the Inflation factor, and degrades to a Soft-skip when the summary cannot be written. Avoid: branch guard (the guard-only design that was rejected), summary hook, safe summary

Effective window: The context window a session's model reports at the moment of use: the catalog value after the llama refresh heal and the context cap clamp. Branch summary budgeting reads only this, never a raw catalog value. Avoid: declared window, cached window (that is the pre-heal catalog value), theoretical window, model window, session context size (that is the current usage, a different quantity)

Inflation factor: The multiplier the Safe branch summary applies to pi's chars/4 estimate when budgeting a branch summary request. It models the worst-case tokenization density of code-heavy content. The default is 2.0. Avoid: safety factor (too generic), padding, overhead, divisor

Soft-skip: The Safe branch summary failure mode in which the navigation completes without a branch summary entry, with a notice. The abandoned branch stays reachable through /tree. Avoid: fallback (implies a summary was produced by another path), cancel (that is the abort outcome), skip (hides the navigation outcome)

Skill command

Skill command: User input that starts with /skill: followed by a skill name, optionally with arguments after it: pi's explicit way to force-load one skill. The name and the arguments are separated by whitespace, and pi's built-in expansion owns the lookup and the <skill> block it records. Avoid: skill invocation (pi's word is command), skill prompt, slash skill

Separator: The whitespace between a skill command's name and its arguments. pi's expansion parses the name up to the first space, so a separator that contains a newline breaks the parse and the command passes through unexpanded; the skill-command extension rewrites that one shape to a single space and leaves every other input untouched. Avoid: delimiter (too generic), separator character (there is a run of them, not one), whitespace (whitespace is also what separates name from arguments in the form pi parses)

Background jobs

Background job: A command started detached from the agent turn by bash_bg, with its state in one on-disk job directory. It outlives the session that started it, so a new session can list it and wait on it. Avoid: background process (generic OS term), detached process, daemon

Job root: The machine-local directory that holds one subdirectory per job: a jobs directory under pi's agent state root (the parent of the session directory), overridable with PI_JOBS_DIR. Machine-level, not per project or per user (ADR 0023). Avoid: state directory (too generic), job directory (that is one job's directory, not the root), cache

Job manifest: The on-disk record in a job directory: the command, the cwd, the label, the wrapper pid, the start time, and the log path. With the log, the child pid file, and the exit code file, it makes a job knowable to a process that did not start it. Avoid: job state (also names the whole directory), job record (fine in prose, but the manifest is the file)

Shell wrapper: The POSIX sh script that runs a job: it starts the command script with its output to the job log, records the child pid, waits, and writes the child's exit code to the job directory. The exit code file is the point: Node's exit status is only readable by the spawner, so the file makes the code knowable to any process. Avoid: runner (too generic), launcher, job script (the job script is the user command, not the wrapper)

Concurrent job bound: The machine-level cap of eight concurrently running jobs. A start beyond the bound is refused with the list of running jobs, so several agents on one machine do not stampede it with detached work. Avoid: job limit (does not say concurrent or machine-level), rate limit (that is a per-time cap, this is a simultaneous one)

TUI

Tool row: The TUI transcript entry for one tool call in an agent turn: the call line from the tool's renderCall slot, with the result block from the renderResult slot below it. Pi's word; its component is ToolExecutionComponent. Avoid: agent turn view (a turn view holds the whole turn, not one call), tool call (that is the LLM-side record), row (too generic)

Docs

Screenshot: A PNG of one extension's UI in the docs site: a TUI view, a footer line, or a CLI's output. Always produced by the Capture script, never taken by hand. Referenced from the extension's own docs page. Avoid: image, picture, capture (capture names the act, not the artifact)

Capture script: The program that renders every Screenshot from the extension's real UI code and the Fixture data. It replaces hand-retaken images: a UI change is a script re-run, and CI fails when a committed Screenshot no longer matches. Avoid: test (tests assert behavior, this produces docs artifacts), screenshot tool

Fixture data: Fixed fictional data the Capture script renders: a fake account, fixed percentages, a small sample repo. Deterministic, so a Screenshot is byte-stable and the capture runs on any machine with no login. Avoid: sample (implies real data, thinned down), mock (a mock stands in for a dependency in a test; fixture data is the data itself), dummy