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.

Developer verification (source checkout)

Install uv first. Frontend scopes also require the Node.js/pnpm toolchain pinned in .github/workflows/frontend.yml. After installing each application's dependencies, run the offline gates through one scoped entry point:

uv run python bin/verify --dry-run --json

uv run python bin/verify --scope core --scope monitor --scope site --json

uv run python bin/verify --scope core --quick --json

uv run python bin/verify --release --dry-run --json

The supported applications are Core, Monitor and site. The default selects all present applications; explicitly selecting an absent application fails instead of silently skipping. Full mode runs tests and builds; quick mode uses stale Elixir tests and omits builds, so it is not full acceptance. Commands have bounded timeouts and keep their output plus a JSON manifest under /tmp/codex-runs/verify-*. The verifier rejects out-of-date frontend dependencies instead of allowing pnpm to auto-install them. No dependencies are installed or Provider calls made by the verifier. Live smoke tests remain separate and opt-in. Frontend CI uses this same entry point and uploads its logs.

--release adds offline acceptance checks for the selected applications, including docs, verifier tests, and Monitor's real five-minute SSE lifecycle. Set PIXIR_MONITOR_BROWSER_BIN to an absolute installed Chrome/Chromium executable when selecting Monitor. The manifest distinguishes requested, executed, completed, and omitted applications; this is not live-model, cross-platform, or publication approval. Frontend release scopes require and report Node 24.x and pnpm 11.5.0 before running application commands; mismatches fail explicitly without changing the toolchain.

doctor --json exposes compiled build_info alongside the serving process's versions and PID. ACP initialization and live Delegate daemon status expose the same identity. Source revisions may be unknown for archive builds; --version remains the semantic version, and a successful source_install_binary check proves existence, not freshness.

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.

Model-aware reasoning effort

Reasoning effort is unset by default; high and the established low/medium/high/xhigh behavior are unchanged. Exact gpt-6-astra also accepts max on Pixir's ChatGPT/Codex Responses backend (HTTP/SSE or WebSocket, with the existing authentication policy):

{"model": "gpt-6-astra", "reasoning": {"effort": "max"}}

Use that in ~/.pixir/config.json. Config preserves max intent and warns about incompatible model/backend combinations rather than silently dropping it. Effective request overrides are checked before authentication or transport. Unknown models, custom providers/routes, Anthropic, and the reasoning-free open_responses profile do not gain max support. ACP advertises max only for compatible selections and rejects an incompatible model switch while max is sticky; choose high or default first. session/set_config_option remains canonical; session/set_model is compatibility-only. These are local admission/request-shape guarantees, not a claim of live backend acceptance. The source checkout includes the detailed note at docs/release-notes/model-aware-reasoning-effort.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.