Pixir Open Beta Quickstart

Copy Markdown View Source

Pixir's first open beta is a developer preview. The supported public surface is the Pixir runtime, terminal CLI, and ACP over stdio. Hex distribution, when used, installs the same CLI/ACP runtime and does not imply a stable public Elixir library API. T3Code pairing is useful for dogfooding through a local adapter, but that adapter is not upstreamed or packaged.

What You Need

  • Elixir compatible with mix.exs.
  • A local checkout of this repository for source installs, or Hex package access for escript installs.
  • Either ChatGPT subscription login through ./pixir login or an OPENAI_API_KEY.

See docs/adr/0016-open-beta-scope.md for the open beta scope and docs/adr/0025-hex-package-scope.md for the CLI/ACP-only Hex package contract.

Install From Hex

mix escript.install hex pixir
pixir help
pixir doctor

Install From Source

mix deps.get
mix escript.build
./pixir help
./pixir doctor

Use JSON output when another agent or script needs to consume diagnostics:

./pixir doctor --json

doctor is local-only and no-network. It checks the runtime version, source-install binary, workspace/session-log writability, local credential presence, config.json shape, and ACP command availability. It may create .pixir/sessions and remove a temporary probe file. It does not prove that the Provider accepts your selected model; use a smoke task for that.

Sign In

./pixir login

Follow the printed device-code instructions. The subscription credential is stored under ~/.pixir/auth.json with local file permissions. As a fallback, set OPENAI_API_KEY.

Run A First Turn

From a project directory:

./pixir "inspect this repo and summarize the architecture"

Pixir writes the model answer to stdout and activity/session details to stderr. Session Logs are stored under .pixir/sessions/ in the workspace and can be resumed:

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

Permission Modes

./pixir --read-only "inspect this repo"
./pixir --ask "make a small change and test it"

--read-only denies mutations. --ask prompts before writes and unsafe shell commands.

ACP Clients

Build the escript first, then point an ACP client at:

./pixir acp

ACP is the beta UI transport contract. Pixir still executes tools internally and reports tool lifecycle through ACP updates.

T3Code Status

T3Code integration is not a packaged public beta path yet. In this repo, T3Code remains dogfood through a local adapter for validating ACP behavior, projection issues, and UX. Do not assume there is an upstream T3 PR or an installable T3 provider package.

If you are using Pixir daily through an ACP client, use the operator checklist in docs/open-beta-daily-driver-ritual.md to keep the local binary, client wiring, and dogfood evidence aligned.

Subagents And Workflows

Pixir supports supervised Subagents and structural Workflows. For beta users, the honest contract is:

  • completed Subagents and Workflow steps may produce useful checkpoint bundles;
  • partial Workflow outcomes are not success;
  • timed-out, failed, cancelled, or detached children must be reported honestly;
  • long-running non-blocking Subagent status/result retrieval is still an experimental UX surface.

Local Verification

The default gate mirrors CI:

mix check

For targeted local checks:

mix pixir.smoke.skills
mix pixir.smoke.subagents
mix pixir.smoke.workflows --dry-run --json
mix pixir.smoke.prompt_cache --dry-run --json
mix pixir.smoke.websocket --dry-run --json
mix pixir.smoke.web_search --dry-run --json

Networked smoke tasks are manual/opt-in. The prompt-cache smoke checks durable cached_tokens observability. The WebSocket smoke checks the Responses continuation shape that Pixir intends to use as the WebSocket-first default Provider path, with HTTP/SSE fallback when WebSocket is unavailable. The Web Search smoke checks hosted Responses Web Search request shape and bounded evidence capture.

Pixir treats image attachments as durable local Session Resources. The original resource is local Pixir evidence; OpenAI input_image is only the Provider projection used when the Turn needs the image. Later Turns should replay descriptors or digests by default unless resource_view explicitly rehydrates the original image.

ACP resource_link blocks are also accepted as Session Resource descriptors. Readable local file:// links are copied into Pixir's local resource store; remote links are recorded as references but are not fetched automatically.

Provider-hosted Web Search is opt-in. It is not MCP and not a local browser tool: OpenAI runs the hosted search and Pixir records bounded source evidence in provider_usage.