# Pixir

<p align="center">
  <img src="assets/brand/pixir-logo-card.svg" alt="Pixir logo" width="320">
</p>

Pixir is an Elixir/OTP runtime for supervised coding-agent work.

Run it from the CLI or an ACP client. Pixir owns the local Session, Subagent
lifecycle, Workflow outcomes, tool execution, failures, timeouts, and replayable
evidence.

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

## Why Pixir

Use any UI. Keep one supervised runtime.

Most coding-agent tools make the chat UI feel like the runtime. Pixir takes the
opposite position: presenters request work; Pixir executes, supervises, and keeps
the evidence.

That matters when agent work becomes long-running or delegated. Subagents need
lifecycle state. Workflows need partial outcomes. Failures and timeouts need to be
inspectable. Pixir records terminal Turn/Subagent evidence and treats partial work as
partial work. Summaries are not evidence; local Logs and artifacts are.

Pixir is for power users and agent operators who want coding-agent work to leave a
durable trail another human or agent can audit.

## Install

From Hex:

```bash
mix escript.install hex pixir
pixir --version
pixir doctor --json
```

From source:

```bash
git clone https://github.com/Ranvier-Technologies/pixir-harness.git
cd pixir-harness

mix deps.get
mix escript.build
./pixir doctor --json
```

## Authenticate

Use ChatGPT subscription login:

```bash
pixir login
```

Or set an OpenAI API key:

```bash
export OPENAI_API_KEY=...
```

## First Run

Run Pixir inside another repository:

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

Ask before writes and unsafe shell commands:

```bash
pixir --ask "make a small safe improvement and run tests"
```

Resume a Session:

```bash
pixir resume <session-id> "continue from there"
```

Inspect local evidence:

```bash
pixir diagnose session <session-id> --json
pixir tree <session-id> --json
```

## Runtime Boundary

Different tools, same boundary: operators and presenters request work; Pixir
executes, supervises, and keeps the evidence.

<p align="center">
  <img src="assets/readme/runtime-boundary.svg" alt="Diagram showing example operators and presenters requesting work through CLI or ACP, while Pixir owns Sessions, Turns, Subagents, Workflows, Provider and Tools, and Evidence Logs." width="860">
</p>

<p align="center">
  <sub>Logos identify example operators or presenters. They do not imply bundled integrations, endorsement, or production support.</sub>
</p>

Pixir is not another chat surface. It is the supervised local runtime underneath
chat surfaces when work needs lifecycle state, tool execution, replay, partial
outcomes, and auditable Logs.

## ACP

Pixir runs behind ACP clients over stdio:

```bash
pixir acp
```

ACP clients present the work. Pixir remains the runtime: it executes tools, records
Events, maintains Session Logs, and reports lifecycle updates.

## What Pixir Includes

- **Runtime:** `Session -> Turn -> Provider -> Tools`, with local Logs as truth.
- **Evidence:** replayable NDJSON Session Logs, Provider usage events, diagnostics,
  replay inspection, and Session/Subagent tree projection.
- **Orchestration:** BEAM-native Subagents, structural Workflows, Workflow Templates,
  checkpoint bundles, durable terminal states, and honest partial outcomes.
- **Operator surfaces:** CLI, ACP stdio, permissions, ChatGPT subscription OAuth,
  API-key fallback, Skills, attachments, and opt-in Provider-hosted Web Search.

## Subagents And Workflows Readiness

Pixir's current Subagent and Workflow contract is operational but deliberately narrow:

- **Supported:** bounded Subagents as supervised child Sessions, structural Workflow
  execution, `wait_agent` partial outcomes, Session/Subagent tree inspection, and
  diagnostics for stale or missing terminal evidence.
- **Verified:** no-network regression gauntlets cover direct CLI fanout and parent-led
  Subagent fanout, including an intentional timeout fixture that must remain honest
  partial evidence instead of clean success.
- **Experimental:** long-running non-blocking client UX, live child-status presentation
  in specific ACP clients, and Workflow Templates as a polished user-facing product
  surface.
- **Not promised:** production scheduling guarantees, cross-client UI parity, or public
  performance claims from local resource-pressure samples.

## Preview Scope

- Not a stable public Elixir library API.
- Not a standalone Pi-style terminal TUI.
- Not an MCP server.
- Not a packaged T3Code provider.
- Not a production/SLA-backed hosted 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.

## Development

For source checkouts:

```bash
mix check
```

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

Networked smoke tasks are manual and opt-in.

## Documentation

- Quickstart: `docs/open-beta-quickstart.md`
- Release notes: `docs/release-notes/open-beta-developer-preview.md`
- Architecture vocabulary: `CONTEXT.md`
- Public contract ADRs:
  - `docs/adr/0016-open-beta-scope.md`
  - `docs/adr/0017-minimal-harness-core-and-interactive-boundary.md`
  - `docs/adr/0018-durable-history-compaction-and-replay-repair.md`
  - `docs/adr/0019-provider-usage-and-prompt-cache.md`
  - `docs/adr/0021-session-resources-and-image-attachments.md`
  - `docs/adr/0022-provider-hosted-web-search.md`
  - `docs/adr/0025-hex-package-scope.md`

Generate local docs:

```bash
mix docs
```

## License

MIT. See `LICENSE`.