Pixir Harness

Copy Markdown View Source

Pixir logo

Pixir is a minimal Elixir/OTP coding-agent harness inspired by Pi: local-first, terminal-first, OpenAI/Codex-first, and intentionally small.

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 an agent runtime.

Pixir is early WIP. The first public shape is a developer preview 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: local Log as truth, explicit tools, cache-aware OpenAI transport, and composable Skills/Subagents/Workflows without turning any UI into the runtime.

What Pixir Includes

  • Local conversation runtime: Session -> Turn -> Provider -> Tools.
  • OpenAI Responses provider with ChatGPT subscription OAuth or API-key fallback.
  • Durable event logs under .pixir/sessions/.
  • 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.
  • BEAM-native Subagents as supervised child Sessions.
  • Structural Workflows over Subagents, including Workflow Templates and checkpoint bundles.
  • 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.
  • ACP over stdio for UI/client experiments.

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 when available:

mix escript.install hex pixir
pixir help
pixir doctor

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

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"

Diagnostics

doctor is local-only and no-network:

./pixir doctor --json

It checks the runtime version, source-install binary, workspace/session-log writability, local credential presence, config shape, and ACP command availability. It does not prove that the provider accepts your selected model; use a smoke task 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 note: docs/release-notes/open-beta-developer-preview.md
  • Architecture vocabulary: CONTEXT.md
  • Decisions: docs/adr/
  • 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
  • Prompt contract and compaction triggers: docs/adr/0020-versioned-prompt-contract-cache-family-and-compaction-triggers.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
  • Skill Context Hydration design: docs/adr/0023-skill-context-hydration.md
  • Session fork and branch summaries: docs/adr/0024-session-fork-and-branch-summaries.md
  • Hex package scope: docs/adr/0025-hex-package-scope.md

Generate local HexDocs-style documentation:

mix docs

License

MIT. See LICENSE.