Pixir

Pixir logo

Pixir is an Elixir/OTP runtime for supervised coding-agent work.

Run it from the CLI or an ACP client. Pixir owns the local Session, Subagent lifecycle, Workflow outcomes, tool execution, failures, timeouts, and replayable evidence.

Pixir is a developer preview. The public package is for operators who want the CLI/ACP runtime; it does not promise a stable Elixir library API.

Why Pixir

Use any UI. Keep one supervised runtime.

Most coding-agent tools make the chat UI feel like the runtime. Pixir takes the opposite position: presenters request work; Pixir executes, supervises, and keeps the evidence.

That matters when agent work becomes long-running or delegated. Subagents need lifecycle state. Workflows need partial outcomes. Failures and timeouts need to be inspectable. Pixir records terminal Turn/Subagent evidence and treats partial work as partial work. Summaries are not evidence; local Logs and artifacts are.

Pixir is for power users and agent operators who want coding-agent work to leave a durable trail another human or agent can audit.

Install

From Hex:

mix escript.install hex pixir

pixir --version

pixir doctor --json

From source:

git clone https://github.com/Ranvier-Technologies/pixir.git

cd pixir



mix deps.get

mix escript.build

./pixir doctor --json

Requires Elixir ~> 1.20. From a source checkout, every pixir ... command below works as ./pixir ... from the repo root — or put it on your PATH first with mix escript.install --force.

Authenticate

Use ChatGPT subscription login:

pixir login

Or set an OpenAI API key:

export OPENAI_API_KEY=...

The default Provider remains ChatGPT/Codex Responses. Source-checkout operators may configure the experimental conservative open_responses HTTP/SSE profile for a validated endpoint, then run mix pixir.smoke.open_responses --dry-run --json before the opt-in live two-call probe. The profile is reasoning-free, does not enable hosted tools, preserves store: false, and makes only a bounded interoperability claim. See docs/open-beta-quickstart.md.

First Run

Run Pixir inside another repository:

cd /path/to/your/project

pixir --read-only "inspect this repo and summarize the architecture"

Start with --read-only when you only need orientation. This keeps the first turn diagnostic and prevents accidental writes while Pixir proves it can create local Session evidence.

Ask before writes and unsafe shell commands:

pixir --ask "make a small safe improvement and run tests"

Resume a Session:

pixir resume <session-id> "continue from there"

Inspect local evidence:

pixir inspect-replay <session-id> --json

pixir diagnose session <session-id> --json

pixir tree <session-id> --json

Runtime Boundary

Different tools, same boundary: operators and presenters request work; Pixir executes, supervises, and keeps the evidence.

Diagram showing example operators and presenters requesting work through CLI or ACP, while Pixir owns Sessions, Turns, Subagents, Workflows, Provider and Tools, and Evidence Logs.

Logos identify example operators or presenters. They do not imply bundled integrations, endorsement, or production support.

Pixir is not another chat surface. It is the supervised local runtime underneath chat surfaces when work needs lifecycle state, tool execution, replay, partial outcomes, and auditable Logs.

ACP

Pixir runs behind ACP clients over stdio:

pixir acp

ACP clients present the work. Pixir remains the runtime: it executes tools, records Events, maintains Session Logs, and reports lifecycle updates.

Presenter Confidence

Pixir's developer-preview confidence is based on the runtime boundary, not on a promise that every client UI projects every detail identically. Local gauntlets have validated the same source-built runtime through the CLI, T3 Code Pixir dogfood, and Zed ACP for basic answers, file-reading turns, and bounded Subagent work.

That is enough to use those presenters for dogfood and operator feedback. It is not a public claim of strict UI parity, production support, or bundled T3/Zed integrations. When a presenter result matters, reconcile the visible answer with Pixir's local Log, inspect-replay, diagnose, and tree output.

Pixir Monitor (Source Checkout Only)

A source checkout includes monitor/, an experimental loopback-only, read-only web Presenter for authoritative Pixir run projections. It is a sibling Phoenix/Bandit app that depends on Pixir; Pixir core and the Hex package do not depend on Phoenix.

cd monitor

mix deps.get

mix escript.build

./pixir-monitor self-check --json

./pixir-monitor serve --dry-run --json

The self-check exercises the built escript against its real ephemeral loopback HTTP listener: it performs the one-use bootstrap internally, fetches the BEAM-embedded JavaScript and CSS, and validates the authoritative Runs envelope without emitting the launch capability. Normal operation uses the filesystem projection source by default. The Runs inventory selects the newest bounded set of Logs and reports total, selected, and truncated counts instead of failing when more Logs exist.

A bounded metadata-only Log watcher emits coalesced SSE invalidation hints. Streams rotate after 300 seconds; rotation, reconnects, errors, and hints all lead clients back to authoritative HTTP snapshots. Listener-port discovery recovers across Endpoint restarts and clears stale port state. Automatic browser launch is Darwin-only and passes its in-memory capability through a private 0700 directory and 0600 FIFO, never in process arguments.

Pixir Monitor is not included in the Hex package, has no packaged install path, and is not a production-supported web UI. Logs remain truth, browser state is disposable, and the Monitor exposes no runtime mutation routes. See docs/adr/0038-pixir-monitor-sibling-spa-sse.md for the experimental contract.

What Pixir Includes

Subagents And Workflows Readiness

Pixir's current Subagent and Workflow contract is operational but deliberately narrow:

For a copyable agent-facing pixir delegate example, including Codex/Claude Code CLI calling patterns, see docs/examples/delegate-cli-live/. Delegate subagent results carry children[].index (the zero-based tasks[] position); the children array order is unspecified, so join results to tasks by index, not position.

Preview Scope

T3Code integration exists as local dogfood through a separate adapter/patch workflow. It is useful for validating ACP behavior, but it is not the primary public install path yet.

Development

For source checkouts:

mix check

mix check runs formatting, warnings-as-errors compilation, tests, escript build, ./pixir doctor --json, a no-network Workflow smoke, and docs generation.

Networked smoke tasks are manual and opt-in.

Documentation

Generate local docs:

mix docs

License

MIT. See LICENSE.