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.