[FEATURE] CLI flag to query session context usage (--context)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

There's no way for external tools to query Claude Code's context usage programmatically. The /context command only works inside an interactive session.

This creates problems when:

• Building IDE extensions that need to display context status
• Creating monitoring dashboards for team usage
• Writing automation scripts that react to context thresholds
• Developing any external tool that needs context data

The current workflow requires manually typing /context inside the session. External applications cannot access this data because:

1. Each Claude session is isolated - starting a new session gives fresh context, not the current session's data
2. The session .jsonl files contain usage data but the format is undocumented and may change
3. There's no CLI flag or API endpoint to query context externally

Proposed Solution

Add a --context flag to query context usage without entering interactive mode.

# Query the most recent/active session in current directory
claude --context

# Query a specific session by ID
claude --context --session-id <session-id>

# JSON output for programmatic consumption
claude --context --output-format json

# Query session in a specific project directory
claude --context --project /path/to/project

JSON output format:

{
"sessionId": "77180c12-152d-404d-9f09-e679318c77ae",
"model": "claude-opus-4-5-20251101",
"context": {
"used": 92000,
"max": 200000,
"percentage": 46
},
"breakdown": {
"systemPrompt": { "tokens": 3000, "percentage": 1.5 },
"systemTools": { "tokens": 19100, "percentage": 9.6 },
"messages": { "tokens": 42300, "percentage": 21.2 },
"freeSpace": { "tokens": 63000, "percentage": 31.6 }
}
}

Alternative Solutions

1. Parsing session files directly - ~/.claude/projects/{project}/{session-id}.jsonl contains usage data, but:

• Format is undocumented and may change between versions
• Requires summing tokens across all messages
• Doesn't include the categorized breakdown

1. Using hooks - Claude Code hooks (PostToolUse, UserPromptSubmit) don't receive context usage data
2. Starting a new session - Running echo "/context" | claude starts a NEW session with fresh context, not the existing session's data

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

1. Developer is in a long Claude Code session working on a complex task
2. An external monitoring tool periodically runs claude --context --output-format json
3. Tool parses the JSON and displays context usage (e.g., "46% used - 92k/200k tokens")
4. When context reaches 80%, tool triggers an alert
5. Developer can proactively manage context instead of hitting limits unexpectedly

Additional Context

_No response_