context-checkup v1.4A

Immutable. This exact content never changes and is served at /api/v1/blob/257f3f061b45dcbc.

---
name: context-checkup
description: Audit what auto-loads into an agent session's context window and suggest lean, reversible fixes to cut startup tokens.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "1.4"
---

# Context checkup

Find what loads **automatically** into the session's context at startup, quantify it, and propose
**reversible** trims ranked by payoff — shrink the startup context window by cutting what isn't
worth its tokens. Read-only — measure and recommend; change settings only on explicit approval.

## Mental model (spend attention top-down)

Cost hierarchy, biggest first:
1. **MCP tool schemas** — large, but **deferred** by tool search. Only a problem if tool search is
   OFF.
2. **Always-on text** — every always-on instruction file (entry-file chain, `@imports`, unscoped
   rules files) and **skill/agent/command descriptions**: every available one's description
   loads every session, except skills flagged non-model-invocable (their description never
   loads; a manual-only skill costs nothing until invoked).
3. **MCP server instructions** — load per enabled server at startup; a chatty preamble can dwarf its
   tool names.
4. **MCP tool names** — ~10 tokens each. Cheap; 30 names ≈ 300 tokens isn't worth a recommendation.

Rules: **measure, never guess** — `wc`/count each source, convert with tokens ≈ words × 1.3 for
prose and characters / 4 otherwise, and state that rule once in the table header. When the agent
has a built-in context breakdown command, ask the user to paste its output and use its numbers as
the baseline; estimate only what it does not break down. **Rank by tokens-saved × reversibility.**
Distinguish **auto-loaded** from **lazy-linked** (nested AGENTS.md referenced from a parent are
*not* loaded — don't flag them).

Tool-name counts, the skills/agents/commands lists, and tool-search status come from the **session's
system-reminders**, not disk — read them from your own context.

## Checklist

Mechanics below are one agent's (settings keys, `~/.claude` paths, which `CLAUDE_CONFIG_DIR`
relocates); on another agent, map each item to its equivalent or ask. `p`, `s` and `r` are the
anchors defined under Useful probes.

**0. Verify tool search is on first.** Evidence is the session itself: MCP tools listed as deferred
(names only, searched on demand) means on, even once a search has pulled some schemas in; full
schemas loaded from the start means off, and every "names are cheap" conclusion flips. Only then
read the env var or setting (`ENABLE_TOOL_SEARCH`, incl. `auto:N` threshold modes) to explain why.

**1. Always-on instruction files.** Measure the entry-file chain (`CLAUDE.md`, `.claude/CLAUDE.md`,
`CLAUDE.local.md`, or `AGENTS.md` and `.claude/AGENTS.md` when read natively) in `p` and
**every parent dir up to root**, the user-level entry file (`~/.claude/CLAUDE.md`), the
managed-policy one (a file such as `/Library/Application Support/ClaudeCode/CLAUDE.md` or
`/etc/claude-code/CLAUDE.md`, or the managed `claudeMd` setting), and every rules file,
subdirectories and symlinks included, in the project and user rules dirs (`$p/.claude/rules/`,
`~/.claude/rules/`) that is not path-scoped (a `paths:` key in its `---` frontmatter; a body
`paths:` line scopes nothing) — a project-rules symlink leading outside the project only once
external imports are approved. Expand `@import` lines (recursive). `wc -w` each; an `AGENTS.md` or
the user-level file counts once, whether read natively, imported or met on the parent walk.

**2. Descriptions (often the largest unexamined chunk).** Skim the in-session lists of **skills,
subagent types, and slash commands** — their descriptions are always loaded, except
non-model-invocable skills (see Mental model). Many rarely-used entries = standing cost. When the
agent offers a skills list with token sizes or a visibility override, take the sizes from it; the
override (e.g. Claude Code's `skillOverrides`) hides a description without editing the skill.

**3. MCP servers.** From `$s/.mcp.json` (a `/cd` does not move it) + settings, list enabled
servers. Count tool **names** per server; note any server with long **instructions**. Flag servers
irrelevant to the user's work.

**4. Enablement levers and hooks.** Read `~/.claude/settings.json`, `$p/.claude/settings.json`,
`$r/.claude/settings.local.json` and, when `s` differs from `r`, the legacy
`$s/.claude/settings.local.json`. Check `enableAllProjectMcpServers`, `enabledMcpjsonServers`,
`enabledPlugins`. Precedence: managed > local > project > user. Each plugin can pull in MCP
servers, skills, agents, hooks. Measure `SessionStart` hook output (from its script, or a run the
user approves) as a startup cost, and per-prompt `UserPromptSubmit` output as a cost per turn. Tool
hooks' plain stdout stays out of the context, but their `additionalContext` enters it, a cost per
matching tool call.

**5. Memory.** Lines of the memory index up to the agent's load cap (e.g. the first 200 lines or
25KB of `MEMORY.md`, whichever comes first); topic files load on demand and are not a startup
cost.

## Output

A short sizes table (source → ≈ tokens → auto-loaded? → relevant to user's work?), then a
prioritized action list. For each action give the exact setting/file edit, the rough savings, and
how to reverse it (prefer per-session toggles). Skip anything under ~a few hundred tokens unless
asked to be exhaustive. Each action names the skill that performs it when available (look in the
agent's skills and plugin dirs, as manual-only skills are missing from the in-session list), with
this skill's own namespace prefix if any: a fat entry file → `/agentify-project` (slimming into
docs); a fat memory index → `/memory-doctor`. Then ask before editing.

## Useful probes

```bash
# anchors — p: the session's primary working directory after any /cd ($PWD when the shell sits there)
# s: the project root the session started in — p resolved below, right without a /cd; after one, or in a desktop-app worktree session (the main checkout root, which also serves its settings and hooks), set it by hand from the session's start context
# r: where settings.local.json lives — the repo root, or the main checkout's root in a linked worktree; outside git, when that root is $HOME, on Windows, or when its .git/.claude is not the user's: p
c=${CLAUDE_CONFIG_DIR:-$HOME/.claude}; p=$PWD; s=$(cd "$p" && pwd -P); g=$(git -C "$s" rev-parse --path-format=absolute --git-common-dir 2>/dev/null); r=${g:+$(dirname "$g")}; { [ -n "$r" ] && [ "$r" != "$HOME" ]; } || r=$p
# always-on instruction files: entry-file chain up to /, user-level and managed entry files, unscoped rules
d=$p; while :; do for f in AGENTS.md .claude/AGENTS.md CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do [ "$d/$f" = "$c/CLAUDE.md" ] || { [ -f "$d/$f" ] && wc -w "$d/$f"; }; done; [ "$d" = / ] && break; d=$(dirname "$d"); done
wc -w "$c/CLAUDE.md" "/Library/Application Support/ClaudeCode/CLAUDE.md" /etc/claude-code/CLAUDE.md 2>/dev/null
find -L "$p/.claude/rules" "$c/rules" -name '*.md' -exec sh -c 'for f; do awk '"'"'NR==1&&$0!="---"{exit 1} NR>1&&$0=="---"{exit 1} NR>1&&/^paths:/{f=1;exit} END{exit !f}'"'"' "$f" || printf "%s\0" "$f"; done' _ {} + 2>/dev/null | xargs -0 -r wc -w
# enabled MCP + settings
{ [ -f "$s/.mcp.json" ] && cat "$s/.mcp.json"; } || echo "no .mcp.json at $s"; cat "$p/.claude/settings.json" "$r/.claude/settings.local.json" 2>/dev/null; [ "$s" = "$r" ] || cat "$s/.claude/settings.local.json" 2>/dev/null; cat "$c/settings.json" 2>/dev/null
```