~/context_forge — README.md

context_forge▋

Your CLAUDE.md is read every message. Keep it small.

// Two shell scripts that keep Claude Code's context small — a status line and a session-start hook — plus 11 skills for trimming it further. Zero runtime dependencies. The portable skills also run on Codex and Gemini CLI.

install view on github
my-app main Fable 5 ctx ███████░░░ 72% md ~312t

the status line, at 72% context with a 240-word CLAUDE.md

the_whole_idea

Every token in CLAUDE.md is paid on every response.

CLAUDE.md−1,042 words
- 1,625 words · ~2,100 tokens, loaded before you type a word- prose rules, repeated defaults, a verify table, three doc layers+ 583 words · ~760 tokens — same constraints, none dropped+ under the hook's own 600-word line, so it never warns on itself

// this repo's own CLAUDE.md, over one day. The hook counts words × 1.3 — an estimate, labelled as one.

session_start_hook

Warns when a CLAUDE.md is over 600 words. Says nothing otherwise.

SessionStart → hooks.json (timeout 15) → session-start.sh ├─ word-counts ~/.claude/CLAUDE.md + <project>/CLAUDE.md ├─ validates ~/.claude/settings.json # stderr only; skipped without python3 ├─ stdout → empty # stdout is injected into Claude's context └─ stderr → ⚠ TOKEN SAVER [WARNING]: CLAUDE.md is 753 words (~978 tokens)

// a hook that saves tokens must not spend them: nothing reaches the model unless a file is over the line.

thresholds

Same four colours for the context bar and the CLAUDE.md estimate.

<50%

green

under 390 tokens of CLAUDE.md

50%

yellow

390+ tokens · time to think about /compact

75%

purple

780+ tokens · run optimize-claudemd

90%

red

1300+ tokens · compact now

// the palette is the tmux "Night City" theme — yellow is your prefix colour, purple your copy-mode colour. Needs a Nerd Font for the separators.

install

Two lines for Claude Code.

# Claude Code
$ claude plugin marketplace add kyuna0312/context_forge
$ claude plugin install context-forge@context-forge

# status line (once)
$ cp ~/.claude/plugins/cache/context-forge/context-forge/*/scripts/statusline-command.sh ~/.claude/
# then in ~/.claude/settings.json: "statusLine": { "type": "command", "command": "bash ~/.claude/statusline-command.sh", "refreshInterval": 30 }

codex

npx skills@latest add kyuna0312/context_forge -a codex

gemini cli

npx skills@latest add kyuna0312/context_forge -a gemini-cli

from a clone (contributors)

bash scripts/install.sh

load in place

claude --plugin-dir /path/to/context_forge

// skills.sh copies the portable skills; skip the ones marked Claude Code only.
// full setup, thresholds and smoke tests in the README.

skills

Eleven prompt files. Six of them run anywhere.

skillwhat it does
/context-forge:optimize-claudemdrewrite a bloated instruction file under 300 words, no constraint dropped
/context-forge:estimate-tokensper-source token estimate with size thresholds
/context-forge:low-token-modeterse replies for the rest of the session
/context-forge:reset-contextpaste-back summary, then compact or clear
/context-forge:task-brain-litedependency-ordered task table, one step per response
/context-forge:llm-wikia wiki the agent reads instead of raw docs
/context-forge:tune-settings · ccdocumented token-saving settings keys, diff + backup first
/context-forge:manage-skills · ccaudit skill descriptions, the only per-session cost
/context-forge:debug-hooks · ccdiagnose failing hooks; ships validate-hooks.sh
/context-forge:project-isolation · ccscope a session to the current project
/context-forge:token-statusline · ccinstall the status line

// cc = Claude Code only (settings.json, hooks, status line). Descriptions total ~350 tokens per session — measured as words × 1.3.