| name | pixi |
| description | shipit's verified knowledge of pixi — the provisioning/run substrate shipit is a thin layer over. Covers what pixi persists, its identifiers, its (near-absent) extension surface, and how shipit's spawn/Tree/eval machinery wires through it. Use when working with pixi, Tree provisioning, environment activation, `pixi run`/`pixi install`, diagnosing "which env is this running in?" issues, or deciding how to integrate a shipit concern WITH pixi rather than around it — so you never have to rediscover pixi's model from scratch. |
| metadata | {"type":"reference"} |
pixi — the substrate (quick reference)
shipit is a thin layer over pixi: build on it, not around it, and never
reinvent what it already does. These are the load-bearing, verified facts;
the full reference (with file:line citations and a refresh procedure) is
docs/dev/pixi.lex (source of truth) / docs/dev/pixi.md.
Verified against pixi 0.71.0 (2026-06-30). pixi moves fast — these facts
drift. If anything below smells stale, re-run the refresh checks in
docs/dev/pixi.lex §9 before trusting it. Never answer pixi questions from
training memory — read the doc or the CLI.
The five things to know
-
pixi is the parent of provisioning + hooks — NOT the agent session.
pixi install provisions a Tree; every Codex hook fires as
pixi run shipit hook <name>. But shipit spawn subagent launches Codex -p
as a bare subprocess (not under pixi run), so pixi is absent from the
agent's process tree.
-
There is no pixi run-id / env-UUID / on-disk log. pixi persists only
static state (envs by name; .pixi/envs/<env>/conda-meta/.pixi-environment-fingerprint
= "provisioned & consistent with the lock"; pixi.lock). So the only stable
per-run correlation key is Codex's session_id (the transcript
filename). Join observability on shipit-owned keys + session_id — pixi gives
you nothing to join on.
-
There is essentially no extension surface. No plugin API, no SPI, no event
hook. The only integration points are [activation] (env/scripts pixi runs on
every activation) and task depends-on — and both only fire when execution
flows through pixi run. Do not design a "pixi plugin." Integrate by
declaring env in [activation] and routing execution through pixi run.
-
Known P0 bug: a spawned agent runs OUTSIDE its Tree's pixi env.
child_env() (src/shipit/spawn/launch.py) does zero activation and cwd=<tree>
does not activate pixi — so the agent inherits the coordinator's (or system)
env, and its python/pytest/shipit resolve to the wrong environment.
Fix: launch through pixi —
pixi run --manifest-path <tree>/pixi.toml --clean-env Codex -p …
(--clean-env also closes the inherited-PIXI_* leak, #167).
-
Only pixi list / pixi info have --json. pixi run/pixi install
emit human stderr only. pixi shell-hook [--json] prints the activation script
(the bridge to activate a Tree env outside pixi run).
When to reach for the full doc
Open docs/dev/pixi.lex when you need: the exact .pixi/ on-disk layout, the
full CLI surface, the complete shipit↔pixi contract (provision/hook/launch
seams), the ranked "lean on pixi harder" list, or the refresh procedure after a
pixi version bump.
