Supervised subagents and workflows for coding agents.

First run · CLI or another coding agent

One worker. One result.
A Log you can inspect.

Start in a project that has a README.md. This example reads that file without editing it. The real run uses your configured provider and its account quota.

1. 01

   Install the published runtime

   You need Elixir 1.20+ and OTP 29+. Add Mix's escript directory to your PATH if your shell cannot find pixir.

   mix escript.install hex pixir
   pixir --version

   Hex installs the CLI/ACP runtime. Monitor and repository delegation Skills are separate source-checkout surfaces.

2. 02

   Choose a provider, then check readiness

   For the ChatGPT subscription route, run pixir login. For API keys or a compatible Open Responses endpoint, follow the provider setup in HexDocs. Keep credentials in your own environment, never in this spec.

   pixir doctor --json

   Read warnings and next actions before continuing. Missing auth is not ready; an absent local ./pixir can be expected when using a Hex-installed binary outside a source checkout.

3. 03

   Inspect a small read-only plan

   Download first-worker.json and save it in your project. Inspect it before running: one explorer, one task, a 120-second child budget.

   View the complete spec

   {
     "contract_version": 1,
     "strategy": "subagents",
     "mode": "read_only",
     "subagents": {
       "workspace_mode": "shared",
       "role": "explorer",
       "max_threads": 1,
       "max_depth": 1
     },
     "tasks": [
       "Read README.md only and summarize this project in three bullets. Do not edit files, run shell commands, or delegate further."
     ],
     "limits": {
       "timeout_ms": 120000
     }
   }

   pixir delegate --spec first-worker.json --dry-run --json --timeout-ms 150000

   Dry-run does not call the model. Continue only if the plan is accepted and would_reject is false. Read-only mode is not an OS sandbox.

4. 04

   Run, then inspect the evidence

   pixir delegate --spec first-worker.json --json --timeout-ms 150000

   Read command_ok, work_complete, each child's status and its answer. A successful command is not proof that the requested work is complete.

   Replace PARENT_SESSION_ID below with the parent_session_id returned by your run:

   pixir tree PARENT_SESSION_ID --json
   pixir diagnose session PARENT_SESSION_ID --json

   A root agent can use the same commands. If a child fails or times out, inspect its evidence and suggested next actions before retrying; do not blindly repeat the whole batch.

Workspace choices

Choose where the work lives.

Isolation and storage are different decisions. Pick the workspace for the task; permissions still determine what a worker can do.

RAM mode is a storage and lifecycle choice, not a speed promise or a general-purpose VM. Canonical Logs and artifacts still persist on disk. In the 0.1.17 candidate, an explicit deliverable keeps a selected virtual result from being replaced by later unmarked reads.