Part of the Brigade fleet from Escoffier Labs
Trim oversize bootstrap files before they truncate.
OpenClaw bootstrap files load into the session prefix on every turn. Past a soft ceiling they get silently truncated mid-session, dropping context with no error. bootstrap-doctor audits each tracked file, flags the sections that should move out, and rewrites the originals with one-line breadcrumbs to relocated reference cards.
The commis of the brigade: keeps the mise en place tight so every section that stays loaded earns its place.
Audit · read-only
- Splits each tracked .md by H2 and H3 headings into sections
- Records char count and the last git-touch time per section
- Shortlists by size, code-block length, staleness, and duplication
- Asks an LLM endpoint to classify each: keep, move, or unsure
- Caches verdicts by content hash, so re-runs stay cheap
Trim · with --apply
- Writes each moved section to memory/cards/<slug>.md
- Replaces the section in the original with a one-line breadcrumb
- Cards land first, so a failure leaves no dangling breadcrumb
- keep is a no-op; unsure is reported but never auto-applied
- Atomic writes, with a path-traversal guard on card slugs
Dry-run by default
status and audit never write. trim shows the plan and stops. Nothing touches a bootstrap file until you pass --apply, so you always see the diff before it happens.
Heuristic shortlist
Flags sections that look offload-worthy: body over 400 chars, a code block longer than 10 lines, no git touch in 60-plus days, or content duplicated across multiple tracked files.
LLM judge with caching
Each shortlisted section is classified keep, move, or unsure by any OpenAI-compatible chat endpoint (Ollama, OpenAI, vLLM). Verdicts cached by SHA256 of the section body, so re-runs are cheap.
Breadcrumbs, not deletions
A moved section becomes a card in memory/cards/ with the existing frontmatter convention. The original keeps a one-line breadcrumb pointing at the card, so the context is relocated, not lost.
Clean git or it refuses
trim --apply refuses to run if the workspace (or a separate cards-dir repo) has a dirty git status, so every change stays revertable. Override with --force when you mean it.
Atomic, ordered writes
Tempfile plus rename means a torn write cannot leave a half-rewritten bootstrap file. Cards are written before originals are rewritten, so a failure never leaves a breadcrumb pointing at a missing card.
| Command | What it does |
|---|---|
| bootstrap-doctor status | Read-only summary of every tracked file: char count, line count, and distance from soft and hard limits across the primary workspace and any named workspaces. Add --json for machine-readable output. |
| bootstrap-doctor audit | Heuristic shortlist plus LLM verdicts. Classifies each oversize section as keep, move, or unsure. No writes. Verdicts cached by content hash; --no-cache forces re-judgement. |
| bootstrap-doctor trim | Builds a plan from move verdicts: write cards, replace sections with breadcrumbs. Dry-run by default. unsure verdicts are never auto-applied. |
| bootstrap-doctor trim --apply | Commit the trim plan. Writes each moved section to memory/cards/<slug>.md and leaves a one-line breadcrumb in the original heading location. |
Config lives at ~/.config/bootstrap-doctor/config.toml and layers in order: built-in defaults, then the config file, then BOOTSTRAP_DOCTOR_ env vars, then CLI flags. Size limits are sourced from brigade.budgets, so the soft and hard ceilings stay in sync across the Escoffier Labs tooling. Requires Python 3.11 or newer.
bootstrap-doctor is part of the Brigade fleet from Escoffier Labs. Browse the source, read the full README, or explore the rest of the kitchen.