Pixir is a minimal, local-first AI coding harness for the terminal, built on the Elixir/BEAM runtime. It is the Pi harness philosophy (tiny core, do real context engineering) reimagined with OTP supervision.
This document is the glossary of domain terms — the shared, precise language of
the project. It is intentionally free of implementation detail. Design and
implementation decisions live in docs/adr/.
Glossary
Harness
The system around a model that turns model completions into an agentic coding runtime. In this 2026 agentic-coding sense, a Harness is not a test harness: it owns the Turn loop, Session lifecycle, History, Tools, permissions, workspace confinement, context loading, skill/subagent/workflow orchestration, credential handling, and presenter/protocol surfaces.
Pixir is the Harness. Codex and Claude Code are also coding Harnesses in this sense. A Provider supplies model completions to the Harness; it does not own agency. Front-ends such as a terminal UI, ACP client, IDE, or T3 Code-style workbench may present or drive a Harness, but they are not automatically the Harness unless they own the agent loop and tool/runtime semantics.
Presenter
A thin human or protocol-facing surface over the Harness. A Presenter may render messages, collect input, subscribe to Events, parse slash commands, attach images, or translate protocol frames, but it does not own Session state, History, permissions, Tools, or the Turn loop.
The CLI renderer, ACP stdio server, and a T3 Code adapter are Presenters or Presenter adapters. They may make interaction nicer, but the Harness remains Pixir.
Presenter Projection
The Presenter-side read model or UI state derived from Pixir Events. A Presenter Projection may store chat bubbles, work-log rows, diff panels, tree views, or local adapter bookkeeping so the UI can reload quickly. It is not the canonical replay source: if it conflicts with the Pixir Log, the Log wins.
In a T3 Code integration, the T3 database owns presentation state and product UX; Pixir owns runtime truth. T3 may supply late UX context such as open files, selected ranges, branch, model selection, diagnostics, and permission choices. Pixir still assembles Provider input through its Prompt Contract, chooses Tools/Skills/Workflows, records Events, and owns Provider transport decisions.
Interactive Layer
The optional Presenter-side layer that turns human interaction into explicit Harness
inputs before a Turn starts. It may resolve /skill commands, expand prompt
templates, select Skills, attach files, render local UI state, or ask for missing
arguments. It must not become a second agent runtime.
In Pi terms, this is the useful part of "interactive": it prepares context and UX around the core loop. In Pixir terms, it belongs at Presenter or adapter boundaries unless the behavior changes durable History or runtime safety.
Session
A single ongoing conversation between a user and Pixir. A Session has an identity, an ordered history, and runs as exactly one Agent role at a time. A Session may have a parent Session and child Sessions (see Subagent). The Session is the unit of agency in Pixir — everything an agent "does" happens within one.
Agent
A named role a Session runs as, defined by: a system prompt, the set of Tools
it may use, and a permission profile (e.g. build = full access, plan =
read-only). An Agent is configuration, not a separate running entity: switching the
Agent changes how the same Session behaves on its next Turn. (Contrast: in the
Kimojo reference, an Agent is its own process; in Pixir it is not.)
Skill
A reusable package of instructions and supporting resources that can guide a Session during a Turn. A Skill is neither an Agent nor a Tool: it changes what the Session knows how to do, not which role it runs as or which capabilities the model can invoke directly.
A Skill is an installed practice for stochastic agent work. It gives the model better priors, language, judgment, examples, failure modes, and reusable workflow shapes. Its supporting resources may include references that teach taste and terminology, templates that structure outputs, and scripts that perform deterministic operations. Loading a Skill does not execute those scripts or run a Workflow by itself; execution still happens through explicit Tools and permissioned Workflow calls.
Discovering a Skill reveals only bounded metadata about the installed practice. Its references, templates, scripts, and assets are supporting resources, not global catalog entries; a Session loads them deliberately when the practice calls for them.
Skill Activation
The fact that a Skill was selected by the user or by the model to guide a specific Turn. A Skill Activation is part of durable History, because replaying or resuming a Session must preserve which Skills shaped the Turn.
Skill Context Hydration
The explicit materialization of dynamic context for a Skill Activation during one
Turn. A Skill package may declare allowed context sources, but the Activation
chooses whether to hydrate one and records the resulting snapshot as a canonical
skill_context_hydration Event.
Hydrated context is not part of the stable Skill body and is not conversational History. When sent to the Provider, it belongs in the late dynamic portion of the Prompt Contract for the current Turn. This preserves cache-friendly Skill instructions while making the exact dynamic facts auditable and replayable.
Pixir does not auto-run arbitrary shell snippets embedded in SKILL.md. Hydration
sources run only through explicit, permissioned, bounded Pixir surfaces, usually
read-only. The source identifier should be named context_source_id to avoid confusion
with Pixir.Provider.
PATCHMD
A repo-local customization maintenance practice for keeping a customized Pixir checkout aligned with canonical upstream changes. PATCHMD is not a Provider, Tool, Workflow, or runtime dependency. It gives humans and Sessions a bounded way to state what is being synchronized, classify incoming changes, preserve local practices, and record acceptance evidence.
Patch Charter
The active statement of one bounded PATCHMD intent: the donor, target, included paths, preserved paths, conflict clusters, public seams, and acceptance checks. A Patch Charter does not replace repo law; it narrows one synchronization or customization task.
Patch Classification
The judgment step that labels donor changes against target constraints. Typical outcomes are to port, preserve, adapt, reject, or defer a change. Classification is the reviewable boundary between upstream movement and user-owned customization.
Patch Evidence Ledger
The durable record of a PATCHMD run: classification, acceptance, proof, status, and handoff artifacts. The ledger records what was checked; it is separate from CI state and external review state.
Patch Operator
A Skill-backed installed practice for carrying out PATCHMD work. The Patch Operator applies judgment and vocabulary; deterministic validation still happens through explicit commands or Tools.
Workflow Template
A reusable Workflow shape supplied by a Skill or by Pixir itself. A Workflow Template captures a practice as a parameterized orchestration recipe: which Agents or Subagents participate, which steps depend on which previous results, what evidence is expected, and what to do on common failure modes.
A Workflow Template is not running state. It becomes a concrete Workflow only when a Session instantiates it with task-specific arguments and executes it through Pixir's normal permissioned Tool surface.
Subagent
A delegated child Session that performs a bounded task for a parent Session. A Subagent has its own Turn context, role/custom-agent configuration, workspace snapshot, permission posture, lifecycle, and Log, while the parent records canonical Subagent lifecycle events so resume/fork can reconstruct the parent-child relationship. A Subagent is not a Skill and not a Tool: Skills change instructions, Tools are capabilities, and Subagents are supervised concurrent workers.
A detached Subagent is one whose durable parent Log proves it existed, but the current
Pixir runtime no longer has a live process handle for it. Detached Subagents remain
queryable by subagent_id and child_session_id; they are reported explicitly instead
of disappearing as not_found.
Workflow
A bounded orchestration plan that coordinates multiple Subagents as one unit of work. A Workflow is neither a Skill nor an Agent: it defines dependency edges between child Sessions, the intended read/write posture of each step, and the condition for collecting terminal summaries.
Workflow dependencies are structural edges, not prose instructions. A step becomes ready only after every step it depends on has reached a terminal result.
Workflows are where Pixir composes stochastic and deterministic work. Subagents perform bounded stochastic work; Tools and scripts provide deterministic operations; the Workflow runtime owns the structural ordering, concurrency, and failure accounting.
Workflow Step
One delegated unit of work inside a Workflow. A Workflow Step names the Agent role to run, the task to perform, its dependency edges, and its declared Read Set / Write Set. At runtime, a Step executes as a Subagent.
Checkpoint Bundle
The structured evidence a Workflow Step produces when downstream work may safely consume its result. A Checkpoint Bundle may include the step id, Subagent id, terminal status, concise summary, produced contract or artifact, verification evidence, known limitations, and whether the result is safe to use as a dependency.
A completed Subagent does not automatically imply a complete Checkpoint Bundle. The Workflow decides whether the terminal result is usable, partial, or requires orchestrator attention.
Partial Workflow Outcome
The honest result of a Workflow that did not fully complete but still produced useful facts. A Partial Workflow Outcome records which steps completed, which steps failed or timed out, which Checkpoint Bundles are usable, which dependent steps were held, and what action is safe next.
Partial outcomes are not successful completion. They exist so presenters and parent agents do not hide timeouts, retry loops, or missing Subagent results behind misleading assistant prose.
Seam Obligation
A named cross-step compatibility concern that must be checked before treating a set of Workflow Step results as integrated. Seam Obligations are created when steps can run in parallel but may still interact through a shared API, schema, file, UI contract, permission rule, or user-visible behavior.
Seam Obligations are different from blocking dependencies: they do not necessarily stop parallel execution, but they must be resolved or consciously deferred before a Workflow claims release-ready completion.
Read Set
The set of Workspace paths a Workflow Step intends to read. Read Sets are used to decide whether shared-workspace readers can safely run beside writers.
Write Set
The set of Workspace paths a Workflow Step may mutate. A read-only step has an empty Write Set. If Pixir cannot derive or receive a narrower Write Set for a writer, the safe default is the whole Workspace.
Turn
One cycle of work a Session performs in response to a single user input: the input goes to the model, which produces a response that may request Tool calls; those tools run and their results are fed back, repeating until the model returns a final answer with no further tool calls. The internal repetitions are tool-loop iterations; the whole input-to-final-answer cycle is the Turn.
Event
A discrete, timestamped fact about what happened in a Session, broadcast on the event bus. Two kinds:
- Canonical events —
user_message,assistant_message(final),reasoning,skill_activation,skill_context_hydration,subagent_event,session_fork,branch_summary,history_compaction,provider_usage,tool_call,tool_result,permission_decision. These are durable: appended to the Session's Log and they define its History. - Ephemeral events — streaming deltas (text, reasoning), status, progress. These are broadcast for live display but never persisted.
Note the two faces of "reasoning" (ADR 0007): the reasoning event carries the
model's encrypted reasoning item (rs_…) — durable, because the Responses API
requires it re-injected on later turns; the reasoning delta is the human-facing
summary text — ephemeral, for live display only.
Log
The per-Session, append-only sequence of canonical Events. The single source of truth for a Session. There is no separate "messages" store — the Log is it.
History
The ordered conversation state of a Session, derived as a fold over its Log. History is a projection, not a stored thing: replaying the Log reconstructs History, and forking a Session means replaying its Log up to a chosen point.
Fork
An inter-Session branch: a new child Session whose Log replays a prefix of a
parent Session's History and then diverges. Pixir does not fork by adding sibling
message pointers inside one Log (contrast Pi /tree intra-file branching). Forks matter
for prompt cache because the shared prefix is exactly the part a Provider can reuse when
requests route to the same cache family via fork_root_session_id.
Branch Summary
A lossy, durable synthesis of context carried into a Fork — not a second History
store and not Compaction of the active branch. In Pixir's first slice it is recorded
optionally when pixir fork creates a child Session, typically condensing the replayed
prefix the child inherited. It is analogous in spirit to Pi branch summarization (keep
abandoned-path context useful) but different in trigger: Pi attaches summaries when
navigating between branches inside one file with /tree; Pixir attaches them at fork
creation across Sessions. A Branch Summary affects future Provider input only when
recorded as a canonical Event with explicit limitations; the full replayed prefix in the
child Log remains authoritative for audit.
Handoff
A transfer of working state to another human, agent, or Session, usually through a summary or explicit instructions. A handoff may be excellent context, but it is not a promise of byte-identical History and should not be treated as prompt-cache reuse by default.
Session Resource
A durable user-provided or Harness-created resource attached to a Session and
referenced from the Log. A Session Resource is not ambient prompt context: future
Provider input may include it, summarize it, or rehydrate it depending on the
Prompt Contract. The architecture is resource-general, but Pixir's first concrete
resource kind is Image Attachment. A payload-backed Session Resource has two
identities: resource_id names the Session/Log reference, while content_sha256
identifies the exact local payload bytes for dedupe, forks, cache evidence, and audit.
ACP resource_link blocks may become payload-backed Session Resources when Pixir can
read a local file:// target; remote links are descriptor-only unless a later explicit
import/fetch records bytes.
Image Attachment
A Session Resource whose payload is an image. An Image Attachment may be represented as original visual content, a descriptor, a lossy visual digest, or a rehydrated Provider image input. A summary of an Image Attachment is not equivalent to the original image. The original image is projected to the Provider on the Turn where it is attached; later Turns replay descriptor or digest by default and rehydrate the original only when visual inspection is explicitly needed. Rehydration is an explicit Tool-mediated action: the user or model may request it, but Pixir records the action instead of silently changing Provider input.
Resource View
The explicit Tool-mediated action that asks Pixir to rehydrate a Session Resource for Provider inspection. A Resource View is not a generic file read and not a Presenter preview: it is a recorded request to project a durable resource across the Leakage Boundary. The first supported Resource View kind is image rehydration.
Session Tree
The branching structure implied by parent and child Session relationships, Subagents, Forks, and optional Branch Summaries. Pixir's canonical representation is still the Log: a tree view is a read-only projection over durable Events and Session ids, not a second store and not an intra-Log message graph.
Compaction
The process of creating a bounded summary of older History when a Session grows
large enough that replaying every item into the Provider is wasteful or impossible.
Compaction is not deletion and not a Presenter convenience: any compacted summary that
affects future model input must be derivable from, or recorded as, durable Log-backed
state. Pixir's first concrete form is a canonical history_compaction Event: Provider
replay sees the latest checkpoint plus the recent uncompressed tail, while the full Log
remains authoritative for audit, repair, and deeper reconstruction.
Summary
A lossy, human- or model-readable synthesis of prior context. A summary may be produced by a human, a model, or deterministic code, and it can be useful context — but by itself it carries no authority: it is not the Log, not a replay checkpoint, and never a source of truth. In Pixir a summary appears as a bounded field inside a Compaction checkpoint or a Branch Summary Event, always labeled with its limitations.
Workspace
The single root directory a Session is allowed to operate within. All file Tools resolve and confine paths to the Workspace; reads or writes outside it are refused. Confinement is the v0.1 safety floor. (The interactive permission gate — asking before risky operations — is post-v0.1; until then a role limits danger only by which Tools it includes.)
Tool
A capability the model can invoke during a Turn — e.g. read, write, bash. A
Tool declares a name, a description, and a parameter schema, and runs to produce a
result. Pixir — not the model and not the Provider — executes Tools: it validates
the arguments against the schema, confines file paths to the Workspace, runs the
Tool, and records a tool_call and tool_result Event. (v0.1 Tools: read,
write, bash.)
Tools are Pixir's deterministic operations boundary. A Skill may recommend a script or command, and a Workflow may sequence many Tools through Subagents, but a Tool remains an explicit, permissioned operation with dry-run, structured errors, and bounded output.
Provider-hosted Tool
A capability executed by the Provider as part of a model response, not by Pixir's
local Tool runtime. Provider-hosted Tools may appear in the OpenAI Responses tools
array, but Pixir does not validate their arguments, run them through
Pixir.Tools.Executor, or record them as local tool_call / tool_result Events.
Provider-hosted Tool evidence belongs to Provider Usage or another explicit Provider-evidence surface. It is durable audit data, not a replacement for Pixir's Log, and it is not replayed as conversational History unless a future Prompt Contract says so.
Provider
The backend that serves model completions to a Session. v0.1 targets a single provider dialect — the OpenAI Responses API — reached with either kind of Credential. Additional providers (Anthropic, local models, etc.) are post-v0.1.
Web Search
Pixir's first concrete Provider-hosted Tool: OpenAI hosted web_search in the
Responses dialect. Web Search is useful when a Turn needs current external facts or
source citations. It is not MCP, not local browser automation, and not a Pixir local
Tool. Pixir may ask the Provider to run it, then record bounded lifecycle/citation/source
evidence so humans and agents can audit what happened.
Web Search output crosses the Leakage Boundary because the Provider receives the query and search context. It should be opt-in at the product layer until Pixir has a clear policy for which Turns may use current web evidence by default.
Leakage Boundary
The point where Pixir projects local Session state, History, Session Resources, Tool results, or other artifacts out of the user's machine to a Provider. Local persistence inside Pixir is not leakage: Pixir is local-first, and the Log, resources, attachments, artifacts, and Presenter projections live on the user's machine by design. Provider input is the boundary where upload policy, rehydration, cache behavior, and user intent matter.
Provider Usage
The token and cache accounting returned by one Provider call. In the OpenAI Responses
dialect, the authoritative prompt-cache evidence is the final stream usage payload,
especially cached_tokens inside the input/prompt token details. Provider Usage is
durable Harness evidence, not conversational context: Pixir records it so humans,
root agents, Subagents, and Workflows can audit cost/cache behavior after the fact, but
it is not replayed back to the model as a message.
Context Pressure
The active Session's Provider-window pressure, derived from Provider Usage and the active model's conservative input-token window. Context Pressure drives warnings, visible recovery, and Presenter gauges. It is not History, not Provider memory, and not model input.
Prompt Cache
The Provider-side reuse of a stable prompt prefix. A cache hit is proven only by observed cached-token accounting, not by latency, intuition, or shorter answers. Prompt cache is compatible with Pixir's local-Log truth because the Provider cache is an optimization; it never becomes the source of Session state.
Cache-Key Family
A short, non-secret routing hint that groups requests expected to share the same stable prefix. A cache-key family should describe the stable surface — model, mode, Session or fork family, Tool set, and Skill index — without raw paths, user text, timestamps, request ids, emails, or secrets. It is portable across supported Provider transports: if Pixir falls back from WebSocket to HTTP/SSE, the same cache-key family should travel with the full replay request. It is a Provider routing hint, not memory, and it does not guarantee by itself that two requests land on the same engine.
Prompt Contract
The versioned agreement about how Provider input is layered: which material is stable cacheable prefix, which is project-stable, and which is late dynamic payload. Authority and cacheability are separate axes — a developer-authority fact can still arrive late, because authority is carried by role, not position. Changing the Prompt Contract is a deliberate lifecycle event: changes are batched, versioned, and observable in Provider Usage evidence rather than shipped as invisible refactors.
Prompt Cache Retention
A Provider request option for keeping eligible prompt-cache entries around longer than
the default ephemeral window. In the public OpenAI API this is expressed as
prompt_cache_retention (for example "24h"), but Pixir treats it as a dialect feature:
the ChatGPT/Codex subscription path must prove support before Pixir sends it. Retention is
still a cache policy, not Session persistence.
WebSocket Continuation
Pixir's preferred Responses transport direction: keep a live WebSocket, create a
Response, and continue from its previous_response_id by sending only new input. The
continuation state is connection-local and finite, and it remains compatible with
store: false because the remote service is not Pixir's durable Session store. If the
socket closes, the model changes, the prompt diverges, compaction rewrites replay shape,
or a Session forks outside the shared prefix, Pixir falls back to full or compacted Log
replay over HTTP/SSE or a fresh WebSocket. Parallel Subagents use separate Provider
connections. A fallback may keep the Cache-Key Family, but it must not assume the
same previous_response_id is still usable.
Credential
The proof of identity a Session presents to a Provider. Two kinds, both reaching the same Responses Provider:
- Subscription — an OAuth token from Sign in with ChatGPT (Codex), drawing on the user's ChatGPT Plus/Pro plan. Auto-refreshes; the primary path.
- API key — a pay-per-token
OPENAI_API_KEY. The fallback path.