# pixir v0.1.7 - Table of Contents

> Elixir/OTP runtime for supervised coding-agent sessions with ACP, Subagents, Workflows, and replayable evidence.

## Pages

- [Pixir](readme.md)

- Public Contract
  - [Pixir — Context](context.md)
  - [Pixir Open Beta Quickstart](open-beta-quickstart.md)
  - [Pixir Harness Open Beta Developer Preview](open-beta-developer-preview.md)
  - [16. Open beta scope starts as source-install developer preview](0016-open-beta-scope.md)
  - [17. Keep the Harness core minimal; put interactivity at Presenter boundaries](0017-minimal-harness-core-and-interactive-boundary.md)
  - [18. Durable History compaction and replay repair](0018-durable-history-compaction-and-replay-repair.md)
  - [19. Provider usage, prompt-cache observability, and WebSocket continuation](0019-provider-usage-and-prompt-cache.md)
  - [21. Session Resources and Image Attachments](0021-session-resources-and-image-attachments.md)
  - [22. Provider-hosted Web Search](0022-provider-hosted-web-search.md)
  - [25. Hex package scope is CLI/ACP-only until public Elixir APIs are explicit](0025-hex-package-scope.md)
  - [26. Runtime terminal-state and replay contract](0026-runtime-terminal-state-and-replay-contract.md)

- Examples
  - [Delegate CLI Live Example](docs-examples-delegate-cli-live-readme.md)
  - [Skill Workflow Template Example](docs-examples-skill-workflow-template-readme.md)
  - [SKILL](docs-examples-skill-workflow-template-skill.md)

## Modules

- [Pixir.BranchSummary](Pixir.BranchSummary.md): Deterministic branch summaries recorded at fork time (ADR 0024).
- [Pixir.CLI](Pixir.CLI.md): Escript entry point — one-shot, print-first (ADR 0001). Commands
- [Pixir.CLI.Sigint](Pixir.CLI.Sigint.md): Installs the CLI interrupt bridge for long-running Pixir turns.
- [Pixir.Compaction](Pixir.Compaction.md): Durable History compaction.
- [Pixir.Config](Pixir.Config.md): Loader for `~/.pixir/config.json` (ADR 0005 ergonomics).
- [Pixir.Delegate](Pixir.Delegate.md): Agent-facing Delegate CLI surface for Codex/GPT callers.
- [Pixir.Delegate.Async](Pixir.Delegate.Async.md): Async/liveness helpers for `pixir delegate` service commands.
- [Pixir.Delegate.CLIContract](Pixir.Delegate.CLIContract.md): Delegate CLI I/O Contract v1.
- [Pixir.Delegate.DaemonClient](Pixir.Delegate.DaemonClient.md): Short-lived CLI client for the workspace-local Delegate daemon.
- [Pixir.Delegate.DaemonCommand](Pixir.Delegate.DaemonCommand.md): CLI-facing command helpers for the manual Delegate daemon.
- [Pixir.Delegate.DaemonEndpoint](Pixir.Delegate.DaemonEndpoint.md): Workspace-local endpoint metadata for the Delegate daemon.
- [Pixir.Delegate.DaemonServer](Pixir.Delegate.DaemonServer.md): Manual foreground Delegate daemon with bounded local IPC.
- [Pixir.Delegate.Evidence](Pixir.Delegate.Evidence.md): Delegate audit-evidence metadata and mirror helpers.
- [Pixir.Delegate.Handle](Pixir.Delegate.Handle.md): Stable Delegate handle helpers.
- [Pixir.Delegate.Owner](Pixir.Delegate.Owner.md): Delegate owner boundary and service-state vocabulary.
- [Pixir.Delegate.OwnerServer](Pixir.Delegate.OwnerServer.md): Current-runtime owner for one Delegate service run.
- [Pixir.Delegate.OwnerSupervisor](Pixir.Delegate.OwnerSupervisor.md): Dynamic supervisor and lookup surface for live Delegate owners.
- [Pixir.Delegate.Progress](Pixir.Delegate.Progress.md): Shared progress-frame contract for Delegate attach observation.
- [Pixir.Delegate.Runner](Pixir.Delegate.Runner.md): Attached runtime runner for `pixir delegate`.
- [Pixir.Doctor](Pixir.Doctor.md): Local first-run diagnostics for the source-install beta path.
- [Pixir.Fork](Pixir.Fork.md): Inter-Session fork planning and execution (ADR 0024).
- [Pixir.Paths](Pixir.Paths.md): Filesystem conventions for Pixir.
- [Pixir.Permissions](Pixir.Permissions.md): Permission policy (ADR 0006). Pure decision function — the Executor consults it and,
for `:ask`, calls a front-end-supplied *asker*.
- [Pixir.Permissions.WritePolicy](Pixir.Permissions.WritePolicy.md): Bounded write policy for headless executor/delegate runs.
- [Pixir.RecoveryCommands](Pixir.RecoveryCommands.md): Copyable recovery command builders for failed or ambiguous Sessions.
- [Pixir.Renderer](Pixir.Renderer.md): The first thin front-end over the event bus (ADR 0004, decision D-05): a stdout
subscriber that pattern-matches on `event.type`. It validates the seam — the core
needs no changes for a new front-end.
- [Pixir.ReplayInspector](Pixir.ReplayInspector.md): Read-only replay inspection for local Pixir Logs.
- [Pixir.SessionDiagnostics](Pixir.SessionDiagnostics.md): Read-only diagnostics for one Pixir Session.
- [Pixir.SessionLease](Pixir.SessionLease.md): Filesystem-backed writer leases for Pixir Sessions.
- [Pixir.SessionResources](Pixir.SessionResources.md): Durable local Session Resources (ADR 0021).
- [Pixir.SessionTree](Pixir.SessionTree.md): Read-only Session tree projection over Pixir Logs.
- [Pixir.Subagents.DelegationContext](Pixir.Subagents.DelegationContext.md): Builds late-bound Delegation Context for Subagent child Turns.
- [Pixir.Subagents.Scheduler](Pixir.Subagents.Scheduler.md): Pure scheduling policy for Subagent fan-out.
- [Pixir.Subagents.WorkspaceSnapshot](Pixir.Subagents.WorkspaceSnapshot.md): BEAM-local physical workspace snapshots for isolated Subagents.
- [Pixir.VirtualOverlay](Pixir.VirtualOverlay.md): BEAM-native virtual workspace runner for future `virtual_overlay` Subagent work.
- [Pixir.WorkflowRun](Pixir.WorkflowRun.md): In-memory ownership boundary for one Workflow execution.
- [Pixir.WorkspaceStrategy](Pixir.WorkspaceStrategy.md): Workspace Strategy vocabulary for Subagents and Workflow steps.

- Runtime Core
  - [Pixir](Pixir.md): Pixir — an OTP-native, terminal-first coding agent.
  - [Pixir.Application](Pixir.Application.md): OTP application root. Starts the long-lived infrastructure that every Session
depends on (see `docs/adr/` for rationale)
  - [Pixir.Conversation](Pixir.Conversation.md): The UI-agnostic multi-turn **driver** (ADR 0008): the conversational loop over
`Session`/`Turn`/`Events`, with no presentation. Every front-end — the terminal CLI,
a future HTTP/WebSocket tier, an editor extension, or an embedding Elixir app — drives
Pixir through this module.
  - [Pixir.Event](Pixir.Event.md): The one Event type (ADR 0004): a plain tagged map with a common envelope
  - [Pixir.Events](Pixir.Events.md): The event bus facade (ADR 0004, decision D-06): the seam between the core and
every front-end. Front-ends subscribe; the core publishes. A renderer is just a
subscriber that pattern-matches on `event.type`.
  - [Pixir.Log](Pixir.Log.md): The per-Session **Log** (ADR 0003 / 0004): an append-only NDJSON file at
`.pixir/sessions/<id>.ndjson`, the single source of truth for a Session.
  - [Pixir.Session](Pixir.Session.md): The unit of agency (ADR 0001): a single GenServer that owns one conversation —
its `:role` (the Agent configuration), its monotonic `seq` counter, and the append
to its **Log**. There is exactly one Session process per `session_id`, registered in
`Pixir.Sessions.Registry`.
  - [Pixir.SessionSupervisor](Pixir.SessionSupervisor.md): `DynamicSupervisor` of `Pixir.Session` processes (ADR 0001). A Session is started
on demand — for a new conversation or to `resume` a persisted one — and is
`:transient`, so it stays down once it finishes cleanly. The CLI may also ask this
supervisor to stop all currently running Sessions during process shutdown so
filesystem writer leases are released before the OS process exits.

  - [Pixir.Turn](Pixir.Turn.md): The tool loop (CONTEXT.md "Turn"): one input-to-final-answer cycle, run inside the
Session's supervised Task (ADR 0001).

- Provider And Auth
  - [Pixir.Auth](Pixir.Auth.md): Owns the Session's **Credential** and serializes token refresh (ADR 0002).
  - [Pixir.Auth.CallbackServer](Pixir.Auth.CallbackServer.md): Short-lived localhost HTTP server for the Codex browser OAuth callback (ADR 0002).
  - [Pixir.Auth.CodexOAuth](Pixir.Auth.CodexOAuth.md): The "Sign in with ChatGPT (Codex)" OAuth flow (ADR 0002), implemented natively over
Finch. Supports **browser PKCE** (localhost callback on `127.0.0.1:1455`) and the
**device-code** fallback for headless environments. Constants and request shapes mirror
the Pi reference implementation.
  - [Pixir.Auth.Store](Pixir.Auth.Store.md): Persistence for the subscription **Credential** at `~/.pixir/auth.json` (ADR 0002).
  - [Pixir.Provider](Pixir.Provider.md): The Provider (ADR 0002/0003/0019): the OpenAI **Responses API** dialect, reached with
either Credential kind. Pixir always sends `store: false`; the local Log remains the
source of truth. The HTTP/SSE path sends folded **History** as full input. The
WebSocket path may use connection-local `previous_response_id` and a late delta as an
optimization, but it never replaces Log replay.
  - [Pixir.Provider.Cache](Pixir.Provider.Cache.md): Prompt-cache key helpers for the OpenAI Responses dialect.
  - [Pixir.Provider.Connection](Pixir.Provider.Connection.md): Per-key WebSocket connection process for the Responses Provider.
  - [Pixir.Provider.ConnectionSupervisor](Pixir.Provider.ConnectionSupervisor.md): Dynamic supervisor for Provider WebSocket connections.
  - [Pixir.Provider.ContextWindow](Pixir.Provider.ContextWindow.md): The conservative model context-window table and the context-pressure gauge
(ADR 0020, "advisory before failure").
  - [Pixir.Provider.FinchTransport](Pixir.Provider.FinchTransport.md): Default `Pixir.Provider.Transport` — streams the Responses request over the shared
`Pixir.Finch` pool via `Finch.stream/5`.

  - [Pixir.Provider.HostedTools](Pixir.Provider.HostedTools.md): Request shaping for Provider-hosted OpenAI tools.
  - [Pixir.Provider.StreamIdle](Pixir.Provider.StreamIdle.md): Per-chunk idle watchdog for Provider streams.
  - [Pixir.Provider.Transport](Pixir.Provider.Transport.md): The seam between `Pixir.Provider` and the network, so the SSE parsing can be tested
without real HTTP. A transport streams an HTTP request and invokes `fun` for each
low-level chunk — mirroring `Finch.stream/5`'s shape
  - [Pixir.Provider.TransportPolicy](Pixir.Provider.TransportPolicy.md): Runtime Provider transport policy.
  - [Pixir.Provider.WebSocketClient](Pixir.Provider.WebSocketClient.md): Minimal Responses WebSocket client used by the production Provider connection.

- Agent Practices
  - [Pixir.Agents](Pixir.Agents.md): Built-in and custom Subagent role discovery (ADR 0011).
  - [Pixir.Skills](Pixir.Skills.md): Progressive-disclosure Skill discovery and loading (ADR 0010).
  - [Pixir.Subagents](Pixir.Subagents.md): Public facade for BEAM-native Subagent orchestration (ADR 0011).
  - [Pixir.Workflows](Pixir.Workflows.md): Deterministic Workflow orchestration over Pixir Subagents.

- Tools
  - [Pixir.Tool](Pixir.Tool.md): The Tool behaviour (CONTEXT.md; the Kimojo-shaped contract minus `risk_level`).
  - [Pixir.Tools.Bash](Pixir.Tools.Bash.md): Run a shell command with the Workspace as the working directory.
  - [Pixir.Tools.CloseAgent](Pixir.Tools.CloseAgent.md): Close or cancel a Subagent thread.
  - [Pixir.Tools.CommandBoundary](Pixir.Tools.CommandBoundary.md): Bounded host-command boundary for local Tool execution (ADR 0027).
  - [Pixir.Tools.Edit](Pixir.Tools.Edit.md): Replace an exact string in a Workspace file (atomic temp+rename). By default
`old_string` must occur exactly once — ambiguous edits fail rather than guess; pass
`replace_all` to replace every occurrence.

  - [Pixir.Tools.Executor](Pixir.Tools.Executor.md): Central tool execution (CONTEXT.md): Pixir — not the model — runs Tools. The Executor
resolves the tool, validates `args` against its schema, then dispatches to `execute/2`
(or `dry_run/2` when `context.dry_run`).
  - [Pixir.Tools.ListAgents](Pixir.Tools.ListAgents.md): List Subagents for the current parent Session.
  - [Pixir.Tools.Read](Pixir.Tools.Read.md): Read a file from the Workspace (read-only; output is token-bounded).
  - [Pixir.Tools.Registry](Pixir.Tools.Registry.md): Compile-time map of tool name → module for the v0.1 built-ins (`read`, `write`,
`bash`). The Executor resolves calls through `fetch/1`; the Provider advertises the
catalogue via `responses_specs/0`.

  - [Pixir.Tools.ResourceView](Pixir.Tools.ResourceView.md): Explicitly rehydrate a local Session Resource for Provider inspection.
  - [Pixir.Tools.RunWorkflow](Pixir.Tools.RunWorkflow.md): Run a deterministic Workflow over supervised Subagents.
  - [Pixir.Tools.SendInput](Pixir.Tools.SendInput.md): Send follow-up input to an idle Subagent.
  - [Pixir.Tools.SkillView](Pixir.Tools.SkillView.md): Load a selected Skill file and record main `SKILL.md` activations.
  - [Pixir.Tools.SkillsList](Pixir.Tools.SkillsList.md): List registered Skills with bounded metadata (ADR 0010).
  - [Pixir.Tools.SpawnAgent](Pixir.Tools.SpawnAgent.md): Spawn or queue a Subagent for a bounded task (ADR 0011).
  - [Pixir.Tools.UpdatePlan](Pixir.Tools.UpdatePlan.md): Record/refine a live plan (to-do checklist) for the current Turn (epic D.1/D.3).
  - [Pixir.Tools.WaitAgent](Pixir.Tools.WaitAgent.md): Wait for Subagents and return an honest fanout outcome.
  - [Pixir.Tools.Workspace](Pixir.Tools.Workspace.md): Workspace confinement (CONTEXT.md): the v0.1 safety floor. File Tools resolve a
user/model-supplied path against the Workspace root and refuse anything that escapes
it. (Symlink resolution is deliberately out of scope for v0.1.)

  - [Pixir.Tools.Write](Pixir.Tools.Write.md): Write a file in the Workspace (atomic temp+rename; creates parent dirs).

- ACP
  - [Pixir.ACP.Protocol](Pixir.ACP.Protocol.md): JSON-RPC 2.0 framing over `Jason`, newline-delimited (ndjson), for the ACP agent
transport (ADR 0009). Pure functions, no IO: one decoded ndjson line becomes a tagged
term; result/error/notification maps become a JSON string (the caller appends `"\n"`).
  - [Pixir.ACP.Server](Pixir.ACP.Server.md): The ACP agent (server side) over stdio (ADR 0009): a single `GenServer` that owns the
stdout writer and the `acp_session_id ↔ pixir_session_id` map, decodes ndjson JSON-RPC
from stdin, dispatches by method onto `Pixir.Conversation`, and runs each
`session/prompt` in a supervised Task.
  - [Pixir.ACP.Translate](Pixir.ACP.Translate.md): Pure mapping from Pixir bus `Events` to ACP `session/update` notification params, and
from a terminal `Conversation.await/2` outcome to an ACP `PromptResponse` stopReason
(ADR 0009, §§4-5). No IO, no process state.

## Mix Tasks

- [mix pixir.bench.codex_pressure](Mix.Tasks.Pixir.Bench.CodexPressure.md): Samples local macOS process and memory pressure while Pixir or Codex work is
running elsewhere.
- [mix pixir.bench.fanout_gauntlet](Mix.Tasks.Pixir.Bench.FanoutGauntlet.md): Runs a bounded fanout regression gauntlet for direct Pixir CLI fanout and
parent-led Subagent fanout.
- [mix pixir.bench.install_t3_harnesses](Mix.Tasks.Pixir.Bench.InstallT3Harnesses.md): Installs Pixir-owned copies of the local-only T3 benchmark harnesses into the paired
T3 Code checkout.
- [mix pixir.bench.real_subagents](Mix.Tasks.Pixir.Bench.RealSubagents.md): Runs small, real-network Subagents gates through the local T3 Code harnesses.
- [mix pixir.bench.subagents](Mix.Tasks.Pixir.Bench.Subagents.md): Runs a deterministic Subagents benchmark and writes evidence artifacts.
- [mix pixir.bench.subagents.blocking_provider](Mix.Tasks.Pixir.Bench.Subagents.BlockingProvider.md)
- [mix pixir.bench.subagents.no_o_auth](Mix.Tasks.Pixir.Bench.Subagents.NoOAuth.md)
- [mix pixir.bench.subagents.writing_provider](Mix.Tasks.Pixir.Bench.Subagents.WritingProvider.md)
- [mix pixir.smoke.e2e](Mix.Tasks.Pixir.Smoke.E2e.md): Walks the whole v0.1 pipeline against the real backend, in a throwaway workspace
- [mix pixir.smoke.login](Mix.Tasks.Pixir.Smoke.Login.md): Exercises the *real* first leg of `pixir login` (ADR 0002): it POSTs to
`auth.openai.com` and prints the device code the server returns. This verifies the
part that unit tests can't — that our `client_id`, endpoint, and request shape are
accepted by the live server.
- [mix pixir.smoke.prompt_cache](Mix.Tasks.Pixir.Smoke.PromptCache.md): Probes whether the Provider reports prompt-cache usage for comparable long-prefix
requests.
- [mix pixir.smoke.skills](Mix.Tasks.Pixir.Smoke.Skills.md): Verifies Pixir Agent Skills end-to-end without hitting the network
- [mix pixir.smoke.skills.no_o_auth](Mix.Tasks.Pixir.Smoke.Skills.NoOAuth.md)
- [mix pixir.smoke.subagents](Mix.Tasks.Pixir.Smoke.Subagents.md): Verifies Pixir Subagents end-to-end without hitting the network
- [mix pixir.smoke.subagents.blocking_provider](Mix.Tasks.Pixir.Smoke.Subagents.BlockingProvider.md)
- [mix pixir.smoke.subagents.no_o_auth](Mix.Tasks.Pixir.Smoke.Subagents.NoOAuth.md)
- [mix pixir.smoke.subagents.writing_provider](Mix.Tasks.Pixir.Smoke.Subagents.WritingProvider.md)
- [mix pixir.smoke.web_search](Mix.Tasks.Pixir.Smoke.WebSearch.md): Probes Pixir's OpenAI Responses hosted `web_search` path.
- [mix pixir.smoke.websocket](Mix.Tasks.Pixir.Smoke.Websocket.md): Runs a bounded real-network smoke against the Responses WebSocket transport.
- [mix pixir.smoke.workflows](Mix.Tasks.Pixir.Smoke.Workflows.md): Verifies Pixir Workflows end-to-end without hitting the network
- [mix pixir.smoke.workflows.echo_provider](Mix.Tasks.Pixir.Smoke.Workflows.EchoProvider.md)
- [mix pixir.smoke.workflows_real](Mix.Tasks.Pixir.Smoke.WorkflowsReal.md): Runs small, bounded Pixir Workflows against the real Provider.

