spawn_agent Subagents are Sessions
Every delegated worker has lifecycle, status, logs, and supervision.
Developer Preview · supervised runtime
Supervised subagents and workflows for coding agents.
Pixir is an Elixir/OTP harness for running 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.
pixir · local runtime
$ mix escript.install hex pixir
Resolving Hex dependencies...
Generated escript pixir with MIX_ENV=prod
$ pixir doctor --json
{"ok":true,"status":"ready","version":"0.1.12"}
$ pixir tree <session-id> --json
{"session":"...","children":[],"log":"append-only"}
Supervised runtime spine
Sessionconversation process
Turnone provider/tool loop
Subagentchild session lifecycle
Workflowstructured step outcomes
Evidencelogs and artifacts
Why Pixir
Use any UI. Keep one supervised runtime.
Pixir sits below the operator and the interface. Codex can plan and audit; Zed, T3Code, or another ACP client can present the work; Pixir runs the supervised local Sessions when tasks need subagents, workflows, lifecycle state, replay, and auditable evidence.
run_workflow Workflows are runtime graphs
Dependencies, concurrency, cancellation, failed steps, timeouts, and partial completion are tracked structurally.
pixir acp Presenters are replaceable
Zed, T3Code, CLI, and other ACP clients can request work while Pixir owns the runtime.
open_responses Bring your own endpoint
The provider layer speaks the Open Responses contract: point it at a hosted or local endpoint, no OpenAI account required.
Runtime Model
Small spine. Supervised consequences.
Pixir keeps the runtime model legible: Session to Turn to Provider to Tools. OTP supervision keeps Sessions, Turns, Subagents, and Workflows as runtime concerns instead of prompt conventions.
01 Start a Session
The workspace gets local runtime state, a session id, and append-only evidence.
02 Run a Turn
Provider calls and tool results flow through one inspectable loop.
03 Delegate safely
Subagents and Workflow steps can complete, fail, time out, detach, or resume.
04 Audit before trust
Summaries are not evidence. Logs, artifacts, and status records are.
Operator Primitives
Commands for operating agent work, not just chatting with it.
Pixir's first public surface is intentionally narrow: CLI and ACP. The primitives are built around diagnostics, continuation, supervision, and local evidence. The machine surface is a checked-in contract with pinned stable fields: docs/cli-contract.md.
pixir doctor --json Check runtime, auth, config, workspace, and ACP readiness from a scriptable diagnostic gate.
pixir resume <session-id> Continue from a durable Session instead of starting over from a transcript pasted into chat.
pixir tree <session-id> --json Project the Session and Subagent hierarchy from local Logs without calling the model.
pixir compact <session-id> --dry-run --json Preview history checkpoints before appending a durable compaction boundary.
pixir fork <session-id> Branch exploration while preserving the original Session as evidence.
pixir acp Run Pixir behind ACP clients while keeping JSON-RPC stdout clean and diagnostics separate.
Runtime Architecture
Presenters drive Pixir. Pixir owns the runtime.
Different tools, same boundary. Operators and presenters request work; Pixir executes, supervises, and keeps the evidence.
Operators & Presenters
Codex meta-orchestrator 
CLI presenter 
Zed ACP client 
T3Code ACP client 
Custom UI ACP client 
Pixir Runtime 
Session conversation process 
Turn provider/tool loop 
Subagents child Sessions 
Workflows structured outcomes 
Provider/Tools permissioned loop 
Evidence Log logs and artifacts Logos identify example operators or presenters. They do not imply bundled integrations, endorsement, or production support.
Evidence Layer
Agent work should leave evidence you control.
Log as truth matters because supervised work needs a durable record. Every run can be inspected, replayed, resumed, forked, compacted, or audited from local artifacts instead of a hidden chat store.
.pixir/sessions/01HQ...ndjson append-only {"ts":"+0.000","event":"session.start","id":"01HQ...","log":"append-only"} {"ts":"+1.204","event":"provider_usage","tokens":1843,"cached_tokens":1190} {"ts":"+1.880","event":"subagent.spawned","parent":"01HQ...","id":"01HR..."} {"ts":"+4.512","event":"workflow.step.failed","step":"build","retry":true} {"ts":"+6.090","event":"workflow.step.ok","step":"build","attempt":2} {"ts":"+7.331","event":"compaction.boundary","kept":42,"dropped":260} $
.pixir/sessions/*.ndjson The Log is truth
Sessions persist as append-only local evidence for replay, repair, inspection, and audit.
provider_usage Cache-aware work is measurable
WebSocket continuation, stable prompt prefixes, and minimal per-turn payloads keep Subagent-heavy work cache-friendly; cached tokens are recorded when the Provider reports them.
pixir tree Hierarchy is inspectable
Parent agents can query Session and Subagent status instead of blocking blindly.
Developer Preview
Preview scope.
Pixir is public enough to install and operate, but the contract is narrow on purpose. The site says this plainly.
scope.terminal Not a Pi TUI replacement Pixir can be daily-driven through ACP, but it is not a finished standalone terminal app.
scope.adapter Not a packaged T3 provider T3 Code pairing is dogfood through a local adapter, not a public install path.
scope.api Not a stable Elixir API Hex installs the CLI/ACP runtime; internal modules are documented for transparency.
scope.sla Not production SLA software No hosted service promises, telemetry, self-update, or enterprise support contract.
Get Started
Install the runtime. Run the diagnostic. Keep the evidence.
Start with Hex when you want the published daily-driver binary. Use a source checkout when you are working on Pixir itself.
$ mix escript.install hex pixir $ pixir doctor --json $ pixir acp