Lesson 2.1 — /add, /remove, and /status: Deliberate Context Management

Lesson 2.1 — /add, /remove, and /status: Deliberate Context Management

THE NAIVE APPROACH TRAP

A developer migrating from Claude.ai to Claude Code brings one instinct: dump everything
into the conversation and let the model figure it out. In the web UI that works because you
paste what you have. In Claude Code, the equivalent is opening a session in a large repo
and immediately asking "refactor the auth module" — trusting that Claude somehow sees the
whole codebase.

It doesn't. Claude Code starts every session with only the system prompt and your CLAUDE.md
in context. Everything else is invisible until you explicitly add it.

The copy-paste migration path looks like this: the developer opens claude in their project
root, then manually types out long file paths to describe what they want changed, or pastes
entire file contents into the chat prompt itself. At one file this works. At three files, the
prompt is 8,000 tokens of raw paste. At ten files — common for any cross-cutting refactor —
the response quality degrades silently as Claude begins operating on partial, out-of-order
file fragments it received as chat text rather than structured context.

The failure compounds at team scale. Two engineers running sessions without context discipline
produce completely different Claude behaviors on the same codebase, because their context
snapshots diverge the moment one of them edits a shared file. Neither session reflects disk
reality. Pair that with no token-cost visibility and you have reproducibility zero, cost
tracking zero, and debugging surface area of "Claude just gave a weird answer."

THE FAILURE MODE

Silent context window overflow. /add src/**/*.py on a 200-file codebase loads 60k–120k
tokens before you type a single message. Claude Code does not warn you. It accepts the add
operations, the /status count climbs, and when you start a multi-round conversation the
model begins truncating early context — which means earlier file contents — silently. The
diff it eventually generates references symbols it can no longer fully see because the file
that defined them scrolled out of the active context window mid-session.

Stale file snapshots. /add reads the file from disk at invocation time and snapshots
that content into context. If a teammate merges a branch that modifies src/models/user.py
while your session is open, your context still holds the pre-merge version. Claude's diff
will conflict at apply-time and you won't understand why because nothing in the UI flags
the staleness. The fix is manual: /remove src/models/user.py, then /add src/models/user.py.
There is no auto-refresh.

Token count underestimation. /status uses a cl100k_base tokenization estimate — the
same tokenizer family as GPT-4. Claude's actual billing tokenizer is claude-tokenizer, which
differs by roughly 5–15% on mixed code/prose content. Treat /status counts as lower bounds,
not exact figures. A session showing 140k/186k effective budget may actually be 151k against
a 200k gross window once you account for the response buffer Claude Code reserves.

ANSI bleed in piped output. If you ever shell out to capture /status programmatically
(in a wrapper script or CI helper), the output contains ANSI escape codes. Piping directly
to grep or jq without stripping those codes first produces garbled output or silent
no-match results. Use claude --print /status 2>&1 | sed 's/x1B[[0-9;]*m//g' to sanitize.
This matters specifically when you build the headless pipelines in Module 3 that introspect
context state.

THE CLAUDEFORGE ARCHITECTURE

/add, /remove, and /status are the foundational context primitives that every
subsequent lesson builds on. Their position in the ClaudeForge system:

Feeds into this lesson: