[ COMMIS · 0.2.0 ]
Keep oversize bootstrap files from silently truncating.
Audits oversize OpenClaw (and similar) bootstrap files against soft and hard char limits, then trims them into reference cards with heuristics plus optional LLM judgment.
Part of the Brigade fleet · brigade.tools · escoffierlabs.dev
[ 01 · WHAT IT DOES ]
The session prefix has a ceiling, and it does not warn you
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.
It is the commis of the brigade: it keeps the mise en place tight so every section that stays loaded earns its place.
[ 02 · FLOW ]
Audit, then trim
[ 03 · FEATURES ]
Dry-run by default
status and audit never write. trim shows the plan and stops. Nothing touches a bootstrap file until you pass --apply.
Heuristic shortlist
Flags sections over 400 chars, a code block longer than 10 lines, no git touch in 60-plus days, or content duplicated across tracked files.
LLM judge with caching
Each shortlisted section is classified keep, move, or unsure by any OpenAI-compatible chat endpoint. Verdicts cached by SHA256 of the section body.
Clean git or it refuses
trim --apply refuses to run if the workspace, or a separate cards-dir repo, has a dirty git status. Override with --force when you mean it.
[ 04 · COMMANDS ]
status Read-only summary of every tracked file: char count, line count, and distance from soft and hard limits. Add --json for machine-readable output. No dependencies beyond the CLI itself. 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. Needs a local or configured LLM endpoint. trim Builds a plan from move verdicts: write cards, replace sections with breadcrumbs. Dry-run by default. unsure verdicts are never auto-applied. 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. status is the dependency-free first step. audit needs a local or configured LLM endpoint (default http://localhost:11434, Ollama; any OpenAI-compatible endpoint works). Config lives at ~/.config/bootstrap-doctor/config.toml and layers built-in defaults, then the config file, then BOOTSTRAP_DOCTOR_ env vars, then CLI flags. Requires Python 3.11 or newer.
[ 05 · TRY IT IN 60 SECONDS ]
$ bootstrap-doctor status
workspace: /home/you/.openclaw/workspace
AGENTS.md 11,805 chars 185 lines OVER soft (10,000)
TOOLS.md 11,589 chars 221 lines OVER soft (10,000)
SOUL.md 8,373 chars 124 lines ok
SAFETY_RULES.md 7,658 chars 118 lines ok
USER.md 7,229 chars 96 lines ok
IDENTITY.md 3,402 chars 52 lines ok
HEARTBEAT.md 2,109 chars 34 lines ok
MEMORY.md 15,720 chars 192 lines OVER hard (11,500)
$ bootstrap-doctor audit
TOOLS.md
## Postiz API endpoints [move] -> postiz-api-endpoints.md
## Eero device culling [keep]
## Jellyfin tool patterns [move] -> jellyfin-tool-patterns.md
AGENTS.md
## codex-builder agent gotchas [unsure]
## ACPX-routed agent pinning [move] -> acpx-routed-agent-pinning.md
$ bootstrap-doctor trim
DRY-RUN. Would write:
memory/cards/postiz-api-endpoints.md (+412 lines)
memory/cards/jellyfin-tool-patterns.md (+58 lines)
Would modify:
TOOLS.md -73 lines (11,589 -> 8,402 chars)
Pass --apply to commit.[ 06 · WHY NOT SOMETHING ELSE ]
A manual eyeball-and-copy pass is the status quo: notice a file is too big, read a section, copy it to memory/cards/, leave a breadcrumb by hand. It gets skipped under load, and the file you miss is the one that truncates. bootstrap-doctor automates the audit-and-relocate loop and stays dry-run so you can review the plan first.
A generic markdown or prose linter measures readability, not the OpenClaw session-prefix budget. It does not know which files load every turn, where the soft and hard ceilings sit, or which sections are active rules versus reference detail. bootstrap-doctor is built around exactly those limits and that keep or move distinction.
wc -c plus a script tells you a file is over budget but not what to move. The judgment of must-stay-loaded versus reference-detail is the hard part, which is why bootstrap-doctor pairs heuristics with an LLM verdict instead of a raw size cutoff.
A hosted memory or context service would mean shipping your bootstrap files off the machine. bootstrap-doctor reads and rewrites local files only. The one optional network call is to an LLM gateway you configure and point wherever you trust.
[ 07 · WHAT IT IS NOT ]
bootstrap-doctor is not a memory manager, a context-compression engine, or an OpenClaw replacement. It does one thing: keep bootstrap files under the prefix budget by relocating reference detail into cards.
It does not summarize, rewrite, or compress your content (a moved section is copied verbatim into a card). It does not decide anything for you on unsure verdicts, those are reported, never auto-applied. It writes nothing without --apply. It does not run in the background, on a schedule, or as a daemon. It does not touch files outside the workspace or cards_dir, and it sends your files nowhere except the LLM gateway you explicitly configure for audit.
[ 08 · INSTALL ]
Install Bootstrap Doctor, then wire it into Brigade when you want the station on your line:
Attach via Brigade:
brigade add memory
Brigade itself:
brigade.tools
·
pipx install brigade-cli
More from Escoffier Labs
Local-first tools for AI coding agents
One kitchen, one brigade. Each tool does one job well, and they share one reviewed source of memory, config, and receipts.