Pixir

Copy Markdown View Source

Pixir logo

Pixir is an Elixir/OTP harness for running coding-agent work as supervised local Sessions.

Drive it from the CLI or ACP clients; Pixir owns Subagent lifecycle, Workflow outcomes, failures, timeouts, and replayable evidence without making the presenter the runtime.

It uses the OpenAI Responses API through either ChatGPT subscription login or an OPENAI_API_KEY, keeps append-only local logs, and exposes both a CLI and ACP over stdio for clients that want to drive it as a local agent runtime.

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

Pixir is for power users doing hard engineering work with local Log as truth, explicit tools, cache-aware OpenAI transport, supervised Subagents, structural Workflows, and diagnostics that another agent or human can audit.

What Pixir Includes

  • Local supervised runtime: Session -> Turn -> Provider -> Tools.
  • CLI and ACP stdio presenters over the same runtime.
  • BEAM-native Subagents as supervised child Sessions.
  • Structural Workflows over Subagents, including Workflow Templates and checkpoint bundles.
  • Replayable local evidence through append-only event logs under .pixir/sessions/.
  • Local diagnostics for doctor checks, Session replay inspection, and lifecycle review.
  • OpenAI Responses provider with ChatGPT subscription OAuth or API-key fallback.
  • Durable Provider usage events for token/cache evidence, including prompt-cache and WebSocket transport observability.
  • Permissioned file, shell, and patch/edit tools.
  • Agent Skills with progressive disclosure.
  • Session Resources for attachments. The initial slice supports Image Attachments and explicit resource_view rehydration.
  • Provider-hosted Web Search as an opt-in OpenAI Responses hosted tool, with bounded source evidence recorded as Provider usage.

What Pixir Is Not Yet

  • Not a stable public Elixir library API.
  • Not an MCP server.
  • Not a packaged T3Code provider.
  • Not a production/SLA-backed agent service.

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.

Quickstart

Install the escript from Hex:

mix escript.install hex pixir
pixir help
pixir doctor --json

Or install from source:

git clone https://github.com/ranvier2d2/pixir-harness.git
cd pixir-harness

mix deps.get
mix escript.build

./pixir help
./pixir doctor --json

Sign in with your ChatGPT subscription:

./pixir login

As a fallback, set OPENAI_API_KEY in your shell.

Run Pixir inside another repository:

cd /path/to/your/project
/path/to/pixir-harness/pixir --read-only "inspect this repo and summarize the architecture"

Ask before writes and unsafe shell commands:

/path/to/pixir-harness/pixir --ask "make a small safe improvement and run tests"

Resume a session:

/path/to/pixir-harness/pixir resume <session-id> "continue from there"

First Diagnostic Loop

Pixir's operator loop is: check the runtime before work, run or resume a Session, then inspect the local evidence after work.

pixir doctor --json
pixir "inspect this repo and summarize the architecture"
pixir diagnose session <session-id> --json
pixir tree <session-id> --json
  • doctor is local-only and no-network. It checks runtime version, binary readiness, workspace/session-log writability, local credential presence, config shape, and ACP command availability.
  • diagnose session is local-only. It audits replay continuity, lifecycle state, and evidence shape from the append-only Session Log.
  • tree is local-only. It projects Session/Subagent hierarchy without calling the model.

Use inspect-replay when you need the lower-level replay reconstruction report:

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

These diagnostics do not prove that the Provider accepts your selected model. Use an explicit smoke task or a real Turn for networked checks.

ACP Clients

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

./pixir acp

Pixir executes tools internally and reports tool lifecycle through ACP updates.

Subagents And Workflows

Pixir supports Subagents and Workflows, but the honest beta 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 experimental UX.

Development

Run the local gate:

mix deps.get
mix check

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

Targeted 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. pixir.smoke.prompt_cache verifies cached_tokens accounting; pixir.smoke.websocket verifies the Responses WebSocket continuation shape that Pixir intends to use as the WebSocket-first default transport with HTTP/SSE fallback; pixir.smoke.web_search verifies hosted Web Search request shape and evidence parsing.

Local Session Inspection

Pixir can project a read-only Session/Subagent tree from local Logs without calling the model or the network:

./pixir tree <session-id>
./pixir tree <session-id> --json

This is a Presenter-facing projection over .pixir/sessions/, not a second message store. Missing child Session Logs are reported honestly so detached or moved Subagents do not disappear as generic not_found runtime state.

When a Session grows large, Pixir can append a durable compaction checkpoint without rewriting or deleting the original Log:

./pixir compact <session-id> --dry-run --json
./pixir compact <session-id> --tail-events 80

Provider replay uses the latest history_compaction checkpoint plus the recent uncompressed tail. The full NDJSON Log remains authoritative for audit and repair.

Documentation

  • Newcomer path: docs/open-beta-quickstart.md
  • Release notes: docs/release-notes/open-beta-developer-preview.md
  • Architecture vocabulary: CONTEXT.md
  • Public contract ADRs:
    • open beta scope: docs/adr/0016-open-beta-scope.md
    • harness boundary: docs/adr/0017-minimal-harness-core-and-interactive-boundary.md
    • compaction/replay repair: docs/adr/0018-durable-history-compaction-and-replay-repair.md
    • provider usage and prompt-cache observability: docs/adr/0019-provider-usage-and-prompt-cache.md
    • Session Resources and Image Attachments: docs/adr/0021-session-resources-and-image-attachments.md
    • Provider-hosted Web Search: docs/adr/0022-provider-hosted-web-search.md
    • Hex package scope: docs/adr/0025-hex-package-scope.md

Generate local HexDocs-style documentation:

mix docs

License

MIT. See LICENSE.