# Pixir Harness
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:
```bash
mix escript.install hex pixir
pixir help
pixir doctor
```
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
```
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"
```
## Diagnostics
`doctor` is local-only and no-network:
```bash
./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:
```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 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:
```bash
mix docs
```
## License
MIT. See `LICENSE`.