agent-ecosystem/.claude/commands/ccc/explain-visible-context.md

name	description
ccc:explain-visible-context	Explains what "Visible Context" is — the 6 trackable token categories, what falls outside tracking, how it's displayed, and why it matters. Use when someone asks about visible context, token attribution, or context window usage.

Present the following explanation directly to the user. Output the full content below as your response — do not summarize, ask follow-up questions, or treat this as background context.

Visible Context

What It Is

"Visible Context" is the portion of Claude's context window that we can identify and measure. Every time Claude processes a turn, its context window fills with various pieces of information — your messages, file contents, tool outputs, thinking, and more. Visible Context tracks what we can attribute to a known source, so you can see where your tokens are going.

What We Track (6 Categories)

CLAUDE.md Files

Memory files that Claude loads automatically at the start of every session and after each compaction. These include:

• Global CLAUDE.md (~/.claude/CLAUDE.md) — your personal instructions across all projects
• Project CLAUDE.md (.claude/CLAUDE.md or CLAUDE.md at project root) — project-specific instructions
• Directory CLAUDE.md — instructions scoped to subdirectories (e.g., src/renderer/CLAUDE.md)

These are injected repeatedly (once per compaction phase), so their token cost accumulates. A 500-token CLAUDE.md file injected across 3 compaction phases costs ~1,500 tokens total.

@-Mentioned Files

Files you reference with @path/to/file in your messages. When you mention a file, Claude Code injects the full file contents into the context. Large files consume significant tokens — a 1,000-line source file could use 5,000+ tokens per mention.

Tool Outputs

Results returned from tool executions: file reads (Read), command output (Bash), search results (Grep, Glob), and others. Every tool result stays in the context window until compaction. A Bash command that prints 500 lines of output or a Read of a large file both count here.

Thinking + Text Output

Claude's own output that consumes context:

• Extended thinking — Claude's internal reasoning (when thinking mode is active). This can be substantial for complex tasks.
• Text output — Claude's visible responses to you. Longer explanations and code blocks use more tokens.

Task Coordination

Messages and operations from Claude Code's team/orchestration features:

• SendMessage — messages between teammates
• TaskCreate, TaskUpdate, TaskList, TaskGet — task management
• TeamCreate, TeamDelete — team lifecycle

Each coordination message adds to the context window of the receiving agent.

User Messages

Your actual prompt text for each turn. This includes the raw text you type, but not the system-injected metadata around it.

What We Don't Track

Visible Context does not cover everything in Claude's context window. The following are present but not attributable by our tracking:

• Claude Code's system prompt — the base instructions that tell Claude how to behave, use tools, format output, etc.
• Tool descriptions — the schema and documentation for each built-in tool (Read, Write, Edit, Bash, Grep, Glob, etc.)
• MCP tool descriptions — schemas for any MCP (Model Context Protocol) servers you have connected
• Custom agent definitions — instructions from .claude/agents/ configurations
• Skill descriptions — the short descriptions of available skills that Claude sees so it knows what's available (visible via /context in Claude Code)
• Internal system reminders — <system-reminder> injections that Claude Code adds for session state, git status, available skills, etc.
• Conversation structure overhead — the message formatting, role markers, and protocol framing around each message

These untracked items form a "base cost" that's always present. You can see what Claude Code injects via the /context command in Claude Code itself.

How It's Displayed

Per-Turn Popover (Context Badge)

Each AI group in the chat shows a small badge. Hovering reveals what was injected at that specific turn — which CLAUDE.md files, which @-mentioned files, which tool outputs contributed tokens.

Token Usage Popover

The token count next to each AI group has an info icon. Hovering shows the standard input/output/cache breakdown, plus an expandable "Visible Context" section showing the percentage of total tokens attributable to each tracked category.

Session Context Panel

A dedicated panel (toggle via the context badge or header button) that shows the full session-wide view:

• All tracked injections grouped by category
• Token estimates per injection
• Phase filtering (if compaction events split the session into phases)
• Total visible context as a percentage of total session tokens

Compaction Phases

When Claude's context window fills up, Claude Code compacts the conversation — summarizing older messages to free space. Each compaction creates a new "phase." Visible Context tracks injections per phase because:

• CLAUDE.md files are re-injected after each compaction
• Previous tool outputs and file contents are summarized away
• The phase selector lets you see what's in context right now (current phase) vs. what was present earlier

Why Visible Context Matters

Understanding where tokens go helps you:

• Spot expensive injections — a massive CLAUDE.md file or a frequently-mentioned large file could be using 20%+ of your context
• Optimize CLAUDE.md — keep memory files concise; every token is repeated across phases
• Be strategic with @-mentions — mentioning a 2,000-line file costs real context space
• Understand compaction impact — see how much context resets after compaction
• Debug unexpected behavior — if Claude seems to "forget" something, check whether it was compacted away