brain

context-discipline

A Claude Code skill for long work: projects that run over many sessions, research surveys, design → spec → plan, and anything that dispatches subagents. It keeps the main agent's context small, and it keeps the project's state on disk, where a compaction or a new session cannot lose it.

New here? Start with the short usage guide — setup, daily use and every /brain command on one page.

The problem

Every API call resends the whole context. When the window fills, Claude Code compacts the conversation into a summary, and detail is lost: the decision made an hour ago, the file that holds the plan, what was running.

The session in which this skill was written, measured afterwards with the repo's ctx-audit.py (from the API usage Claude Code saves with every call):

• Main thread: 1,514 API calls and 6 compactions (4 manual, 2 automatic). Between compactions the context peaked at 232k to 967k tokens, in a 1M-token window.
• Input processed: 706M tokens in the main thread (98% of them cache reads) and 597M more in 149 subagents.
• What filled it: at the six peaks the context added up to 4.22M tokens. 54% of that is not in the transcript at all (system prompt, tool schemas, thinking sent back without its text, estimation error). The visible rest:

Most of the visible part was work a subagent could have done, or reading and printing more than needed. This is one session, by the author, and the skill was written partway through it: it motivates the skill and proves nothing about it. (An earlier version of this README quoted "1.39M tokens, 5 compactions" and larger shares, such as Bash output at 19%. Those came from a characters/4 estimate of the visible content, taken before the session ended, not from a measurement.)

What you get

• The skill (context-discipline/SKILL.md): where each kind of information lives, the delegation contract, design → spec → plan with subagents, cheap reviews, and how to handle compaction.
• Brains for sessions: a brain is a name plus a folder holding STATUS.md (current state), 00-Project-Overview.md (big picture and dated decision log), decisions/ and handoffs/. It belongs to a Claude Code session, not to a folder: you attach one to a window with /brain (a small user-invoked skill running scripts/brain.sh), and several windows may share one. See Brains.
• Three hooks, active only when the session has a brain:
  • SessionStart (brain-hook.sh) prints the brain's STATUS file on startup, resume, /clear, compaction and fork, so the current state is back in context automatically. A session with no brain gets a one-line hint instead.
  • PostCompact (compact-log.sh) saves each compaction summary to ~/.claude/brain-logs/<name>/, so you can check what a compaction kept.
  • UserPromptSubmit (ctx-nudge.sh) adds a short note for Claude when the context reaches 40% of its window, and every 15% after: at the next natural break, update STATUS and suggest /clear or /compact <focus>. It also says once when another session changed STATUS.
• Agent brief templates (references/agent-briefs.md): research, context gathering, spec and plan drafting, implementation, review and fact-checking, each with a short hand-back contract.
• ctx-audit (scripts/ctx-audit.py): measures a past session's context from API usage (peaks, compactions, subagents) and estimates which visible content filled it.

How it works

Claude Code session: startup / resume / /clear / compaction / fork
        |
        v
SessionStart hook (global, in ~/.claude/settings.json) runs brain-hook.sh
        |
        v
which brain did this window attach?  /brain paper (kept per Claude Code process), else CD_BRAIN=paper
        |                                                  |
        v                                                  v
brains.json: paper -> ~/.claude/brains/paper/          none: one line, "No brain attached. Brains: paper,
prints its STATUS.md and "(Project brain loaded ...)"        thesis. Type /brain <name> to attach one."

The folder the session runs in plays no part: two windows in one repo can work on different brains, and one brain can follow you across repos. The other two hooks use the same brain. A registered STATUS must be a text file inside the brain's folder; anything else is refused with a one-line warning.

The delegation contract, which the skill applies to every subagent:

1. The subagent writes its full output (survey, review, spec draft) to a file with a dated name.
2. It hands back at most about 15 lines: status, verdict, key issues as one-liners, the file path.
3. Inputs go in as file paths, not pasted text.
4. One task per dispatch, with an agent type that can write files.
5. The main agent keeps decisions and pointers, not documents, and records each decision on disk at once.

Requirements

• Claude Code
• bash and python3 (3.9 or later for the context note; jq is used if present, but not needed)
• macOS or Linux. Windows is untested.

Quick install

git clone https://github.com/adityakumar68/context-discipline-skill.git
cd context-discipline-skill
./install.sh

Claude Code picks up the new hooks within a few seconds. Open /hooks to check that the SessionStart, PostCompact and UserPromptSubmit hooks are listed, and restart Claude Code only if they are not.

What the installer changes

It works in $CLAUDE_CONFIG_DIR if set, else ~/.claude, and changes four things:

1. The skill. Copies context-discipline/ to ~/.claude/skills/context-discipline/. A different copy already there is first moved to ~/.claude/skill-backups/context-discipline.bak-<timestamp> (outside skills/, so Claude Code does not load it as a second skill).
2. The /brain skill. Copies brain/ to ~/.claude/skills/brain/ with the same backup rule. A different skill already called brain (one that does not run this repo's brain.sh) is left alone, and the summary says /brain was not installed.
3. The hooks. Adds three hooks to ~/.claude/settings.json, each in one entry with no matcher: SessionStart runs brain-hook.sh and PostCompact runs compact-log.sh, each with a 10-second timeout, and UserPromptSubmit runs ctx-nudge.sh with a 5-second timeout. Each command reads bash "$HOME/.claude/skills/context-discipline/scripts/<script>", so a settings file synced between machines works on each (a config folder outside $HOME gets absolute paths). Older entries for the same scripts are replaced, including the four SessionStart entries with matchers that earlier versions installed, and an entry whose script path no longer exists is repaired. Every other key and hook is kept. The file is edited with python's json module (rewritten with 2-space indentation; a final newline, or its absence, is kept), written atomically, and first backed up to settings.json.bak-<timestamp>. If it is not valid JSON, the installer stops and changes nothing. It warns if "disableAllHooks": true is set.
4. One line in ~/.claude/CLAUDE.md (backed up first; skipped if a line already mentions context-discipline, or with --skip-claude-md; the line an earlier version appended is replaced). The line is shown under Manual install.

It also converts a brains.json registry of version 1 (an earlier version's) to version 2, after a backup.

Run `./install