Crux

A scientific-method lab notebook your AI agent drives. crux keeps a falsifiable
question → hypothesis → evidence tree for your project, so nothing gets silently
p-hacked or forgotten across dozens of experiments. The agent runs the loop;
you make the calls.

What it is

_{You talk science; the notebook fills. The conversation never mentions crux. On the right, agents keep the science tree, the literature wiki and the task list in step with the talk — checks written down before the run, so the verdict is derived from the bar you set, not argued from the number that came back. The agent supplies the evidence; the verdict is yours.}

Months in, can you still say what you asked, what you tested, and whether each question is
settled? crux keeps that explicit:

• Questions — what you don't know. They carry no answer of their own; they resolve by aggregating the findings beneath them, and they nest.
• Hypotheses — falsifiable leaves under a question, each with pre-registered verifiables (pass/fail checks written down before running: "ADE20K val mIoU ≥ supervised + 2.0, 3-seed mean"), its findings, and the report and figures the run produced. Only hypotheses are tested.
• A plain-Python engine does the bookkeeping: IDs, tree consistency, evidence tallied upward, a human review gate, a regenerated META.md + EXPERIMENTS.md.
• An LLM agent drives it; you (the PI) make the calls — which questions matter, where the bar sits, when a question is answered.

Nothing counts until you sign off.

Install

Needs Python ≥ 3.8 (the engine is stdlib-only) and git; the npx path also needs
Node.js. Install all four crux skills with any skills.sh-compatible
agent — Claude Code, Cursor, Codex, Windsurf, Copilot CLI, and others:

npx skills add mehdiforoozandeh/crux --all

Or clone and symlink them into your agent's skills dirs:

git clone https://github.com/mehdiforoozandeh/crux
cd crux && ./install.sh

Restart your agent and you're set — ./crux selftest checks the install. Scopes,
per-agent notes, updating, and troubleshooting: installation guide.

Try it in 60 seconds

No agent, no dependencies, nothing to configure — open the cockpit over the bundled
example vault from a fresh clone:

git clone https://github.com/mehdiforoozandeh/crux
cd crux && ./crux serve --dir skills/crux/examples/segssl_vault

That's segssl_vault (5 questions, 16 hypotheses —
the vault behind the screenshots below): pan the status-colored tree, open h1's evidence
ledger and its rendered report with figures, flip to the Wiki tab for the literature
graph. (Port taken? --port 8890.)

The cockpit

Your vault opens in Obsidian, but crux has a purpose-built home for it. crux serve
is a dependency-free, read-only browser cockpit: pan / zoom / search the live tree,
focus one question, watch the review gate, read any node's evidence ledger, and open a
hypothesis's report — rendered markdown, figures and all — beside the tree. Edits still
go through your agent or the CLI.

_{The cockpit over the segssl_vault example — the status-colored tree (branches collapse/expand) and a hypothesis's evidence ledger (verifiables · metric · run link · finding). Read-only; every edit goes through your agent or the crux CLI. (Real screenshot; it matches your GitHub light/dark theme.)}

The literature wiki gets its own view too. The crux-wiki skill — inspired by
Karpathy's LLM-wiki idea —
compiles PI-curated sources into a knowledge base, drawn here as a graph colored by
category, sized by links, cross-linked into the question tree, flowing one way:
literature → wiki → tree.

_{The literature wiki as crux's own knowledge graph — pages by category, sized by links, cross-linked with the question tree. Compiled by the crux-wiki skill from PI-curated sources.}

License

Crux — the Southern Cross, the sky's most reliable signpost. It keeps you oriented to the crux of each question.

MIT © Mehdi Foroozandeh