Glossary

The language of this Pi runtime: what each local term means and which words to avoid for it. This page owns naming, not behavior, schemas, or rationale; follow each link for behavior, and read the decision records for why a hard-to-reverse choice was made. The object model holds how the runtime’s nouns relate, their lifecycles, the verbs, and their Pi sources. Entries run from foundational concepts to their dependents.

Change terms with domain modeling: one entry per concept, one or two sentences on what it is, rejected names under Avoid, and no behavior or implementation detail. Where Pi has a word, use it with Pi’s meaning (decision). Vocabulary used only inside one package stays in that package’s terms, such as the supervisor’s. At about 55 entries or 1,800 words, review stale entries before adding more; this is a maintenance prompt, not a limit, reset to that baseline when the glossary took Pi’s model.

Runtime and context

Agent directory — The directory Pi reads its configuration and runtime state from, normally ~/.pi/agent. It is not the session’s working directory. See configuration.

Brain — The instructions, configuration, and evaluators kept outside extension packages: skills/, evals/, and pi/. See the brain. Avoid: brain for the whole repository.

Primary checkout — The ~/code/my-pi checkout that the live runtime reads. A feature worktree never replaces it. See activation.

Activation — Making merged content live by updating the primary checkout and reloading the session. A merge alone is delivery, not activation. See candidate versus live source. Avoid: deploy.

Extension package — An independently versioned unit of owned Pi behavior under extensions/packages/. See inventory. Avoid: extension (alone, when package versus entrypoint matters).

Library package — Plain TypeScript that an extension package and an app may both import; Pi does not load it. See decision 0010. Avoid: shared package, which names shared.

Entrypoint — A file a package’s manifest names for Pi to load and register behavior. A package can have several; the modules it imports are not entrypoints. See adding a package.

Skill — Task-selected instructions read from a SKILL.md file. The canonical tree lives here; the LP copy is a generated mirror. See the brain.

Agent definition — A named file whose description is one roster line and whose body is appended to a subagent’s task. It points to a canonical method and adds child-only limits. See agent definitions. Avoid: wrapper, profile, role.

Roster — The agent definitions a session can launch as subagents, shown to the model one line each. See subagents. Avoid: roster for the models enabled in settings.

Profile — A named set of model providers a session may use, configured in my-pi settings. See profiles. Avoid: account, mode.

AI Gateway — The separate repository and Docker service running CLIProxyAPI that the cliproxyapi provider connections reach. It is not the providers extension, which owns this repository’s provider registration. Avoid: AI Gateway for the providers package.

Provider connection — One configured endpoint, credential source, and transport that Pi offers as a physical provider, an entry of aiGateway.providers in my-pi settings. A connection is either a subscription (cliproxyapi) or a direct provider that declares its own models. Avoid: gateway profile; Profile names the session policy above. See providers.

my-pi settings — The my-pi.json file in Pi’s agent directory, one section per owned package. Distinct from Pi’s settings.json. See my-pi settings.

Instruction root — The checkout whose skills and agent definitions a candidate trial reads. It is the primary checkout unless a trial selects another. See candidate trial.

Instruction projection — A temporary agent directory that points instructions at the selected instruction root while borrowing specified runtime state. It is not complete runtime isolation. See candidate trial.

Session — One saved Pi conversation: a file of entries in a tree, with its current runtime context. worktree enter changes its work root, not the session. See the object model.

Launch cwd — Pi’s session cwd, fixed for the session file. Project resources load from it. See work root.

Work root — The directory a session’s tools operate in: the launch cwd until worktree enter points them at a worktree. See work root. Avoid: session switch, moving the session.

Transcript — The entries of a session’s active branch, as recorded. See the object model. Avoid: transcript for what a frontend or display draws, which is the transcript view.

Frontend — A separate program that owns all presentation of a Pi session and drives Pi through Pi core, such as the TUI app. Pi’s native TUI, even with display’s changes, is not a frontend. See frontends. Avoid: client (alone), UI.

Pi core — A frontend’s backend: the library that runs Pi in RPC mode and keeps the session as a view model for the frontend to draw. See Pi core. It is not Pi’s pi-agent-core package. Avoid: client core; backend for Pi itself; SDK, which names Pi’s in-process API.

Frontend bridge — Pi core’s extension, loaded only into the Pi it starts, that adds to Pi’s RPC stream what a frontend needs but Pi does not send, such as work-status rows, for Pi core to read. See frontend bridge. Avoid: bridge (alone).

Clink — A chat-agent app at apps/clink/ that runs channels and agents in one process on pi-durable. See clink. Avoid: Clankworks, the predecessor it replaces.

Clink instance — An app that depends on clink and defines one deployment, such as Jobson at apps/jobson. See clink. Avoid: tenant, which is a mono app.

Execution and coordination

Input — Something submitted for the model to answer: a prompt, a steer, a follow-up, or a wake. Inputs waiting for a boundary are Pi’s queue. See the object model. Avoid: inbox, for the queue; the supervisor’s inbox keeps its name.

Run — The turns from one input to its answer, where a turn is Pi’s one assistant response and its tool calls. A steer joins the current run; a follow-up starts the next. See the object model. Avoid: turn (alone); run for the span until the session settles, which is busy.

Answer — The assistant message that ends a run without tool calls. It answers the run’s input and every steer that joined the run. See the object model.

Busy, idle, settling — A session is busy while a run is active, including from one queued run to the next, and idle once Pi will not continue on its own. Becoming idle, Pi’s agent_settled, is settling. See the object model.

User turn — One request to the agent and all the work for it, until its final answer. Its user is whoever the agent answers: a person, a frontend, a parent agent, a Goal, or a supervisor. See the object model. Avoid: turn (alone), which is Pi’s turn; display turn; exchange.

Final answer — A user turn’s last answer, once nothing it launched can wake the session. See the object model.

Task — A unit of work with an owner and an outcome: a tool call or an async task. See the object model.

Owner — What a task belongs to. See the object model.

Outcome — How a task ended: completed, failed, or aborted. See the object model.

Async task — A task launched by a call that returns at once and running outside its session’s busy and abort scope: a shell task or a subagent. Pi’s durable harness calls it a background task. See the object model and asynchronous work. Avoid: background task.

Shell task — An async task that runs one shell process group, with its output file: the bg tool’s object, owned by the async-tasks package. See the object model and lifecycle. Avoid: background task, background job.

Persistent job — A shell task that runs until stopped, such as a dev server. See status widget.

Child — A Pi session owned by a task in another session: a subagent’s child or a supervised one. See subagents and supervisor terms. Avoid: worker (one agent definition’s name).

Subagent — An async task that owns a headless child launched from an agent definition, with its own session and one result. See subagents.

Result — What an async task hands back when it ends: its outcome and output, delivered to its session as a message. It is not a notice, Pi’s transient UI message. See the object model. Avoid: notification, completion notice.

Wake — A delivered result that triggers a run: an input from an async task rather than the user, whose run belongs to its origin’s user turn. Goal and the supervisor send wakes of their own, and each of those starts a user turn. See the object model and extension-triggered runs.

Origin — The user turn whose run launched an async task. See the object model.

Wake-capable — Said of an async task whose result will wake the session: not persistent, with delivery and its run trigger on. See the object model.

Settle report — A subagent child’s own reading of its user turn after each settle: waiting on its wake-capable work, or done. See subagent lifecycle. Avoid: auto-exit, idle grace.

Pane agent — A coding agent running in a Herdr pane and driven through Herdr’s agent lifecycle. It is not a child. See the herdr skill.

Aside — A fork of the current session opened as its own Pi session in a Herdr pane. The parent neither changes nor tracks it. See tui-aside. Avoid: btw, side chat.

Goal — A session’s one durable objective, which authorizes automatic continuation within cost and active-time limits until it completes, blocks, or is cancelled. See Goal.

Coordinator — A session that directs children instead of doing their work. In a supervisor project, it is the session holding the lease. See coordinator role.

Supervisor project — One plan under supervisor management. Its units, attempts, lease, inbox, and verifiers are defined in the supervisor terms. Avoid: project (alone), which can mean a repository or checkout.

Presentation

Transcript view — The transcript as a frontend or display draws it. Display can hide rows of the view, never entries. See the object model and display contract. Avoid: transcript, for what is drawn.

Segment — The transcript view’s span of one user turn, which draws one assistant message; a steer can start another inside it. See draw rule.

Status block — Display’s block at the end of the transcript view while a user turn runs or waits, holding the latest answer text and the user turn’s work table: the running user turn’s, else the newest waiting one’s. It is presentation, not a session entry. See status block. Avoid: turn panel.

Status row — Display’s single row above the editor for running state, other user turns’ waits, worktree changes, and persistent jobs. See status row. Avoid: status line.

Answer summary — A done user turn’s active time and tool-call count, distinct from the line display draws from it. See the record and answer summary. Avoid: turn summary.

Work-status row — One unit of work a producer publishes to display’s shared store. The producer owns the work; display owns its rendering. See work status store.

Native peek — Pi’s native transcript view, shown while display temporarily hides its own additions. See display contract.

Footer — The session fields below the editor, distinct from the status row and status block. See footer. Avoid: statusline, the upstream name for a footer.

Design reference — An HTML page of full-screen frames that records a user interface’s intended design. It holds only the UI; behavior stays with its owner. See design references.

Method and evidence

Behavioral owner — The document that owns a supported consumer-visible promise, such as a package README with its docs/ pages. A test or glossary does not replace it. See authority.

Behavior map — A capability-organized description of observable behavior that routes to behavioral owners. A benchmark’s reference map is a behavior map of an upstream source. See my-pi’s map.

Loader smoke — An isolated check that entrypoints load and register without loader errors. It starts no session and proves no lifecycle behavior. See loader smoke.

Host probe — A check of a Pi compatibility seam an extension depends on, sometimes pinned to a host version. It is not complete interactive validation. See TUI checks.

Instruction qualification — A judgment from actual task traces, outcomes, and independent assessment for stated models and configuration. Valid frontmatter alone does not qualify instructions. See instruction checks.