Modules
Pixir — an OTP-native, terminal-first coding agent.
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").
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.
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.
Built-in and custom Subagent role discovery (ADR 0011).
OTP application root. Starts the long-lived infrastructure that every Session
depends on (see docs/adr/ for rationale)
Owns the Session's Credential and serializes token refresh (ADR 0002).
Short-lived localhost HTTP server for the Codex browser OAuth callback (ADR 0002).
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.
Persistence for the subscription Credential at ~/.pixir/auth.json (ADR 0002).
Deterministic branch summaries recorded at fork time (ADR 0024).
Escript entry point — one-shot, print-first (ADR 0001). Commands
Durable History compaction.
Loader for ~/.pixir/config.json (ADR 0005 ergonomics).
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.
Local first-run diagnostics for the source-install beta path.
The one Event type (ADR 0004): a plain tagged map with a common envelope
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.
Inter-Session fork planning and execution (ADR 0024).
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.
Filesystem conventions for Pixir.
Permission policy (ADR 0006). Pure decision function — the Executor consults it and,
for :ask, calls a front-end-supplied asker.
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.
Prompt-cache key helpers for the OpenAI Responses dialect.
Per-key WebSocket connection process for the Responses Provider.
Dynamic supervisor for Provider WebSocket connections.
The conservative model context-window table and the context-pressure gauge (ADR 0020, "advisory before failure").
Default Pixir.Provider.Transport — streams the Responses request over the shared
Pixir.Finch pool via Finch.stream/5.
Request shaping for Provider-hosted OpenAI tools.
Per-chunk idle watchdog for Provider streams.
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
Runtime Provider transport policy.
Minimal Responses WebSocket client used by the production Provider connection.
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.
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.
Durable local Session Resources (ADR 0021).
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.
Read-only Session tree projection over Pixir Logs.
Progressive-disclosure Skill discovery and loading (ADR 0010).
Public facade for BEAM-native Subagent orchestration (ADR 0011).
The Tool behaviour (CONTEXT.md; the Kimojo-shaped contract minus risk_level).
Run a shell command with the Workspace as the working directory.
Close or cancel a Subagent thread.
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.
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).
List Subagents for the current parent Session.
Read a file from the Workspace (read-only; output is token-bounded).
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.
Explicitly rehydrate a local Session Resource for Provider inspection.
Run a deterministic Workflow over supervised Subagents.
Send follow-up input to an idle Subagent.
Load a selected Skill file and record main SKILL.md activations.
List registered Skills with bounded metadata (ADR 0010).
Spawn or queue a Subagent for a bounded task (ADR 0011).
Record/refine a live plan (to-do checklist) for the current Turn (epic D.1/D.3).
Wait for Subagents to finish and return compact summaries.
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.)
Write a file in the Workspace (atomic temp+rename; creates parent dirs).
The tool loop (CONTEXT.md "Turn"): one input-to-final-answer cycle, run inside the Session's supervised Task (ADR 0001).
Deterministic Workflow orchestration over Pixir Subagents.
Mix Tasks
Installs Pixir-owned copies of the local-only T3 benchmark harnesses into the paired T3 Code checkout.
Runs small, real-network Subagents gates through the local T3 Code harnesses.
Runs a deterministic Subagents benchmark and writes evidence artifacts.
Walks the whole v0.1 pipeline against the real backend, in a throwaway workspace
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.
Probes whether the Provider reports prompt-cache usage for comparable long-prefix requests.
Verifies Pixir Agent Skills end-to-end without hitting the network
Verifies Pixir Subagents end-to-end without hitting the network
Probes Pixir's OpenAI Responses hosted web_search path.
Runs a bounded real-network smoke against the Responses WebSocket transport.
Verifies Pixir Workflows end-to-end without hitting the network
Runs small, bounded Pixir Workflows against the real Provider.