# pixir v0.1.0 - Table of Contents

> OTP-native, local-first coding agent runtime with ACP, Skills, Subagents, and Workflows.

## Pages

- [Pixir](readme.md)

- Project Context
  - [Pixir — Context](context.md)
  - [Pixir — Roadmap (post-v0.1)](roadmap.md)
  - [Pixir Open Beta Quickstart](open-beta-quickstart.md)

- ADRs
  - [1. Single-process Session; Agent is configuration](0001-single-process-session.md)
  - [2. Codex (ChatGPT subscription) OAuth + OpenAI Responses API as the primary provider](0002-codex-oauth-responses-provider.md)
  - [3. Stateless Turns; local Log is the source of truth; prompt-cache deferred](0003-stateless-turns-local-log-source-of-truth.md)
  - [4. Unified event log; tagged-map Event envelope](0004-unified-event-log-and-envelope.md)
  - [5. Agent ergonomics: dry-run, self-describing help, structured errors, I/O discipline](0005-agent-ergonomics-dry-run-help-structured-errors-io-discipline.md)
  - [6. Permission model: auto-run by default, smart opt-in gating](0006-permission-model-auto-by-default.md)
  - [7. Reasoning items are canonical and replayed; summary text stays ephemeral](0007-reasoning-item-persistence-and-replay.md)
  - [8. A UI-agnostic conversational driver; the bus is the only observation seam](0008-ui-agnostic-conversation-driver.md)
  - [9. ACP (Agent Client Protocol) is the front-end transport; Pixir is the agent](0009-acp-agent-transport.md)
  - [10. Agent Skills use progressive disclosure with durable activations](0010-agent-skills-progressive-disclosure.md)
  - [11. Subagents are supervised child Sessions](0011-beam-native-subagents.md)
  - [12. Workflows are structural orchestration over Subagents](0012-structural-workflows-over-subagents.md)
  - [13. Skills can provide Workflow Templates as installed practices](0013-skill-backed-workflow-templates.md)
  - [14. Workflows report Checkpoint Bundles and honest partial outcomes](0014-workflow-checkpoint-bundles-and-partial-outcomes.md)
  - [15. PATCHMD maintains Pixir customization against canonical upstream](0015-patchmd-customization-maintenance.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)
  - [20. Versioned prompt contract, cache-key family, and compaction triggers](0020-versioned-prompt-contract-cache-family-and-compaction-triggers.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)
  - [23. Skill Context Hydration is explicit, canonical, and late-bound](0023-skill-context-hydration.md)
  - [24. Session fork and branch summaries (Log-backed, inter-session)](0024-session-fork-and-branch-summaries.md)
  - [25. Hex package scope is CLI/ACP-only until public Elixir APIs are explicit](0025-hex-package-scope.md)
  - [AGENTS.md - Pixir ADRs](agents.md)

- Examples
  - [AGENTS.md - Pixir Examples](docs-examples-agents.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.Compaction](Pixir.Compaction.md): Durable History compaction.
- [Pixir.Config](Pixir.Config.md): Loader for `~/.pixir/config.json` (ADR 0005 ergonomics).
- [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.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.SessionResources](Pixir.SessionResources.md): Durable local Session Resources (ADR 0021).
- [Pixir.SessionTree](Pixir.SessionTree.md): Read-only Session tree projection over Pixir Logs.

- 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.

  - [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.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 to finish and return compact summaries.
  - [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.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.

