ballast
ballast is a Claude Code and Codex plugin that takes a goal you have no expertise in, builds it up from the foundations, and carries it through — then keeps every solved path so the next goal starts further along.
A few weeks into working with Claude, this piles up:
- You give the same correction again next month
- A settled decision reopens, or quietly changes
- You act on an unsourced answer, and find out later
- Your copy names a feature nobody built yet
- "Done" turns out to mean Claude said so
- What you shipped stalls its first reader
- Another model's tidy summary lands as fact
- You re-research what the project already wrote down
All eight have one cause: the weight sits in the conversation and nowhere else. Ships fix this by loading weight low in the hull, under everything else — that weight is called ballast. Here, it is rules, decisions, and verified facts riding in files, under the conversation.
And it accumulates. A method you only found after dead ends, a fact that survived checking, a vague problem finally cut into pieces — each one stays, and the next goal starts on top of it. You do not dig the same hole twice.
The smallest piece of that, live in a session — the first symptom on the list, with a rule you set once, weeks ago:
> add a setup script — npm install and we're done
[ballast] Standing rules that apply to this request:
- Use pnpm here: This repo uses pnpm. npm install has broken the
lockfile twice; write scripts and commands with pnpm.
Claude: Using pnpm — your rule says npm broke the lockfile twice.
The setup script runs pnpm install.
The [ballast] block is the guaranteed part: "npm" matched your rule, so its full text arrived with this message. The reply line is illustrative — the hook guarantees delivery, not obedience.
At a glance
- What it is: a Claude Code / Codex CLI plugin — one hook script (node, zero dependencies, zero network) on four events (
UserPromptSubmit,PreToolUse,PreCompact,SessionStart), plus sixteen markdown skills. - What the hook does: delivers the full text of your own standing rules from a JSON catalog into the request they match — at the prompt, at the tool call a rule names, and just before context compaction. Every delivery is logged as rule ids and counts, never as prompt text.
- What the skills cover: an append-only decision ledger, verification labels for claims, a proof standard for external claims, goal decomposition, checkpoints, recall, corrections-into-rules (pin), rehearsal, delegated research, a knowledge base, memory scaffolding, skill authoring, an agent-owned schedule (fixed dates, event triggers, launch bundles), and three operations skills (setup, doctor, report).
- What it is not: not multi-agent orchestration, not automatic memory collection or summarization, not provider switching or routing, not a style pack. You write the rules; the plugin delivers them.
Install
/plugin marketplace add svy04/ballast
/plugin install ballast@ballast
Two lines in Claude Code and you are done. The hook runs on the node (≥ 18) already on your PATH; the other sixteen pieces are markdown skills. (The install id reads plugin@marketplace — both happen to be named ballast here.) For a guided first setup — no JSON in sight — say "set up ballast" or call /ballast:setup.
Pairing it with a style skill? ballast shapes what the model remembers and what counts as done, not how it talks, so terse-reply skills such as caveman sit beside it without conflict. The one place they meet is memory/: keep compression tools away from the ledger and knowledge files — the memory-compress-guard example rule guards exactly that. For plain-language replies, copy the example catalog's reader-first rule.
Using Codex instead? The same repository installs as a Codex plugin — codex plugin marketplace add svy04/ballast, then codex plugin add ballast@ballast — and the same hook runs there: Codex loads hooks/hooks.json once you trust it in /hooks. Without the plugin, a project-level .codex/hooks.json does the same, and the bundled codex exec wrapper stays for builds without hooks: docs/CODEX.md.
- Zero dependencies, zero network — the hook is one script, imports only
fs/os/path; it reads local files and prints. ballast itself sends nothing anywhere (the optional verifier/researcher commands are local CLIs you configure, and the separate verify script only spawnsnodeto re-run the hook) - One hook (four events) + sixteen skills — only the hook is code-enforced, and the docs label which is which
- Ships empty, and says so — every session opens with one line,
[ballast] hook live — N rules loaded, zero at first; on messages the hook stays silent until a rule matches. Quick start is how rules get there. Standing cost: the sixteen skill descriptions are about 665 words; skill bodies load only when a skill is invoked - Delivery log, ids only — each delivery appends one JSON line (timestamp, rule ids, sizes — never prompt or tool text) to
~/.claude/ballast/log.jsonl, rotated past ~512 KB;--reportaggregates it into fires per rule and names the rules that never fired;BALLAST_NO_LOG=1turns it off - Hook verified on 20 cases, in five groups — delivery (keyword inject, silence on no match, block, legacy input fields) · failure (a broken catalog says so, and still never blocks; the manifest is in the shape Claude Code loads) · status line (with rules, without a catalog, with a broken one, after compaction) · log (ids only, never text;
BALLAST_NO_LOGwrites nothing) · tool layer and modes (injects, denies, silent for unnamed tools, out of prompts; the compaction reminder;--report/--checknaming fired, dead and broken rules). The harness checks what the hook emits, not whether the model obeys; runnode hooks/scripts/verify-hook.mjsin a clone to re-check - MIT — the whole mechanism is readable in an afternoon
How it runs
Hand it something big — /ballast:goal ship the pricing page — and every piece attaches to that one goal, in order.
It starts from what is already held. At the session's first reply, the recall skill has swept the files brain-init scaffolded on day one — index, knowledge, decisions, rules, skills, all five, past the first hit. The goal skill then splits the objective into branches and judges each one against that inventory.
A covered branch must use its file: the pricing rule already in the catalog and the brand facts in memory/knowledge/ come along as they are, and nothing already held gets re-researched. A bare branch makes learning its first task.
A bare branch starts with questions, not answers. In a field you have never worked in, your sense of what matters is the least reliable thing you have. So the terrain scan collects what is argued, what is settled, and where beginners get burned, and lays them out as a map.
Then the branch is cut top-down into a pyramid of atomic pieces: no overlaps, nothing missing, each leaf small enough to verify on its own. A sub-field exposed mid-work is registered by name the moment it appears. Unfilled is allowed; unnamed is not.
Leaves fill bottom-up, and nothing bears weight unverified. Collection can be handed to a second CLI (researcher), whose findings arrive hearsay — it can fetch, but it cannot rule. Every leaf faces the verify gate — refuted first, sourced, labeled — and what survives lands in memory/knowledge/.
The skeleton itself lives in memory/goal/pricing-page.md: the tree, its gaps, the next leaf. Tomorrow's session resumes from that file.
The work runs on prepared ground. Quality is set before the work, not patched after it. Mid-work you correct Claude once — "prices include VAT" — and pin writes that into the rule catalog; the hook delivers it with every message that matches, and only those. A standing rule rides along just when its keywords appear.
Anything said about the product outside the repo passes proof-standard first. External claims come from a truth file — a record of what verifiably works, evidence attached. No entry, no claim.
Done is a claim, so done passes a check. A zero-context reader walks the deliverable cold (rehearsal); the check passes when a round comes back stall-free, and that round's log is the evidence. A passed check is a file that exists, a test that runs, an output actually inspected.
What the goal solved then stays. Decisions go to the ledger, changed only by supersede — and only what the user actually said goes in; a reading of their silence stays in open questions.
A procedure that will recur becomes a skill (skill-forge), and a pause becomes a thirty-second return (checkpoint). Next quarter's pricing page opens on the solved path.
The same loop, drawn — boxes are pieces, cylinders are files that outlive the session:
flowchart TD
G["a goal arrives — /ballast:goal"] --> M{"mobilize:<br/>already held in rules,<br/>knowledge, skills?"}
M -- "held → using it is mandatory" --> W["the work"]
M -- "gap → learn first" --> L["terrain scan → top-down skeleton →<br/>bottom-up leaves, each verified"]
L -. "co