# Pixir
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:
```bash
mix escript.install hex pixir
pixir help
pixir doctor --json
```
Or install from source:
```bash
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:
```bash
./pixir login
```
As a fallback, set `OPENAI_API_KEY` in your shell.
Run Pixir inside another repository:
```bash
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:
```bash
/path/to/pixir-harness/pixir --ask "make a small safe improvement and run tests"
```
Resume a session:
```bash
/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.
```bash
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:
```bash
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:
```bash
./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:
```bash
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:
```bash
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:
```bash
./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:
```bash
./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:
```bash
mix docs
```
## License
MIT. See `LICENSE`.