broomva parallax
Parallax is a simulation runtime built so that it cannot lie about being a simulation. It is not trying to be a simulator that is right; it is trying to be one whose reproducibility you can check in five seconds.
It is the bstack's ontology simulation layer: where a proposed change is modelled and accepted before it is applied anywhere else.
Repository: https://github.com/broomva/skills, at skills/simulation/parallax/ ·
hub: https://parallax-hub.onrender.com
Install
There is one copy of this skill and it is this one, so there is one address:
npx skills add broomva/skills --skill parallax -g -a claude-code
The runtime comes with it, at runtime/ inside the installed skill --
installing the skill installs the layer. Building it is what puts parallax on
PATH, and it needs Bun.
The path below is where -g -a claude-code puts it. This block names it in full
rather than opening with a bare cd runtime, because a reader copies these lines
from wherever they happen to be standing, and a relative cd that silently
depends on an unstated cwd is the same defect this skill's own
tests/test_skill_md_claims.py exists to catch:
cd ~/.claude/skills/parallax/runtime
bun install
bun link # puts `parallax` on PATH
parallax help
Installed somewhere else -- a different agent target, a project-scoped install, or
a clone of the monorepo -- substitute that location; the three commands are the
same, and runtime/ is always directly inside the skill.
Or drive it as tools inside an agent, with no dependency on ai or zod:
import { generateText } from "ai";
import { parallaxTools } from "./runtime/src/tools";
await generateText({ model, tools: parallaxTools(), prompt });
The flow
Nine commands, one for each tool. The order a thread uses them:
| Step | Command | What it is |
|---|---|---|
| 1 | parallax status |
where this workspace stands, read from disk |
| 2 | parallax propose |
an ontology built from what is actually in the directory |
| 3 | parallax render |
re-send the proposal byte-for-byte |
| 4 | parallax parse-reply --text <msg> |
classify a human's reply; records nothing |
| 5 | parallax answer --answer <n>=<value> |
record answers without accepting |
| 6 | parallax accept --by <who> |
the gate: nothing simulates before this |
| 7 | parallax run --horizon N --seed N |
roll forward, write a receipt |
| 8 | parallax receipt --run <id> |
locate or export the receipt |
| — | parallax reject --reason <why> |
archive a refusal; refusals are kept |
Add --json to any of them for the {ok, value} envelope. Same values, different
framing.
The four rules that are not guessable
1. Read the state from disk, never from the conversation. A Parallax session is
a new OS process every turn, and an ActiveOntology is branded with a
module-private symbol that does not survive a JSON round-trip — trust cannot be
serialised. So "we already accepted that" is not a thing you can remember; it is a
thing you look up. Call parallax status first on any turn that mentions
accepting, running, answering, or a previous proposal.
2. Relay text verbatim. Never restate a number. propose and run return a
rendered text. Send it as-is. A restated number is an invented number the moment
it is wrong, and a paraphrased proposal that a human then accepts is an acceptance
of the paraphrase — which is why render exists and re-summarising does not.
3. n indexes the STORED proposal. The numbering the human was shown is the
numbering that binds them. Never renumber the questions yourself.
4. A refusal is a code, not a sentence. Every surface returns
{ok:false,error:{code,reason,detail?}}. reason is for the human; code is what
you branch on. Exit 2 is a typed refusal — a gate doing its job. Exit 1 is a defect.
The deterministic core
Two lookups, because reasoning about them is how they go wrong:
Both run from the workspace Parallax is reading, so the script is addressed by
its own location and never relatively. parallax status reports on the directory
you are standing in; cd-ing into the skill to reach the script would make the
skill directory the workspace, which fails silently by succeeding on the wrong
context.
SKILL="$HOME/.claude/skills/parallax" # a checkout instead: <repo>/skills/simulation/parallax
# what to do next, from the state on disk
parallax status --json | python3 "$SKILL/scripts/parallax_next.py" --status -
# next: parallax answer --proposal 94c50e77db74 --answer 1=<value>
# why: 1 blocking question(s) open, no answers recorded yet. ...
# what a refusal actually means
parallax run --json 2>err.json || python3 "$SKILL/scripts/parallax_next.py" --error err.json
# NO_ACCEPTED_ONTOLOGY
# Nothing has been accepted in this workspace. Accept a proposal first.
next comes back null when no Parallax command applies -- an unreadable
workspace is the case -- rather than naming the command that produced the result.
--json on either for a machine-readable answer. Exit 0 determined, 3 the
document parsed but names no state or code on file, 2 the input is not that
document.
scripts/parallax_next.py carries a remedy for all 52
error codes, and the set is pinned against
references/error-codes.txt — captured from
runtime/src/tools/errors.ts at a named commit. A code added in the runtime with
no remedy here goes red rather than being answered with an invented one.
The two refusals that look like bugs and are not
RECONCILIATION_UNACKNOWLEDGED on accept. The executable domain ignores fields
the human was shown as read from their own context. Tell them first — relay
detail.unmappedFromContext — and only then retry with --acknowledge-unmapped.
Setting the flag without telling them defeats the gate, which is the product.
An empty workspace that should not be empty. Inside a sandboxed session a
derived path is denied, and a denied read comes back as an empty directory
rather than an error. So a wrong path does not fail; it reads as "your workspace
has nothing in it". Do not retry with a path you computed. There is no path argument
on the tool surface for exactly this reason — --root is CLI-only, where the person
typing the path is the confinement.
What Parallax will not tell you
Nothing here is calibrated against a real business. There are no transcripts. The runtime README and the landing page both say so, and it should stay said. If you need an accuracy number, Parallax deliberately does not publish one — determinism is what it offers instead.
An MCP server is not built. The seam is cut and reads finished — toolSpecs()
hands out every tool as data, and a test asserts every tool name is legal as an MCP
tool name — but only the transport is missing. Do not tell anyone to connect over MCP.
Contributing to Parallax itself
Read runtime/AGENTS.md. The short version: three gates, all
run from runtime/, in order — bun test, bun run typecheck (bun test does
not typecheck), bun run mutants (a passing suite is not a testing suite).
Tests
Run from the skill's own directory. The path below is relative on purpose, because
this skill has two homes and only a relative path is correct in both:
skills/simulation/parallax/ in broomva/skills (canonical), and
~/.claude/skills/parallax/ once installed.
python3 -m pytest tests/ -q # 44 passed (37 hermetic + 7 live-CLI)
The 7 live-CLI tests skip unless parallax is on PATH (bun link in this
skill's runtime/). A run reporting 37 passed, 7 skipped is the expected result
without it; 44 passed means the remedy table was checked against the real binary.
tests/test_skill_md_claims.py asserts the path and the count above are true, because
this section was wrong when it shipped: it named skills/tooling/parallax/tests/,
which does not resolve from an install, and said 29 when there were 36. A documented
command a reader copies and cannot run teaches them the skill is broken -- and a
skill with more than one home is exactly where an absolute path rots first.