[FEATURE] Native context visibility for self-regulating multi-context workflows

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

Claude Code has no visibility into its own context usage. This creates three failure modes:

1. Unpredictable walls - Context fills up, Claude Code forces /compact or /new at inconvenient times (mid-implementation, mid-thought). The user loses control of when breaks happen.

1. Fixed phase guessing - Users pre-plan "Phase 1, Phase 2" etc., but these are predictions about context cost, not reality. Phases end up too small (wasted handoffs) or too large (hit the wall unexpectedly).

1. Auto-compact degradation - If enabled, summarization kicks in mid-work, losing nuance and potentially confusing running agents.

The core issue: Claude cannot self-regulate because it cannot see how full its context is. The data exists - the statusline feature receives tokens, max, and percentage - but Claude has no access to read it.

Additionally, while agents exist for delegating work, there's no guidance on using them as an orchestrator pattern to keep the main context lean during large implementation tasks. Users discover this by trial and error, if at all.

Workflow impact:

• Large implementation tasks that should be straightforward become unpredictable
• Users can't confidently start multi-file work without risking mid-task context exhaustion
• No standardized way to hand off work between contexts when breaks are needed

Proposed Solution

1. Native Context Visibility

Expose context usage to Claude directly. Options (in order of preference):

• A built-in tool - GetContextUsage returning {percentage, tokens, max}
• A system variable - Something Claude can reference directly
• File-based - Write the existing statusline data to a file Claude can read by default (this is what we hacked together)

2. Context-Aware Workflow Guidance

Add system prompt guidance for large tasks:

• "When context exceeds 85%, stop at a clean boundary and prepare for handoff"
• "For multi-file implementations, act as orchestrator: read for understanding, delegate implementation to agents, receive summaries"
• "Agent results return summaries, not full code - use this to keep main context lean"

3. Plan Continuation Support

Native support for picking up work in fresh contexts:

• Plan picker - Show available plans with titles when continuing
• Context tracking - Track which context completed which items (ctx1, ctx2 markers)
• File references - Plans include specific files to read per checklist item, enabling targeted context building

Ideal User Experience

1. User starts large task, Claude creates a plan with checklist
2. Claude works as orchestrator - reads for understanding, delegates implementation to agents
3. Claude monitors its own context, stops at 85%: "Stopping at 85%. Run /new then invoke /continue."
4. Fresh context loads plan, sees what's done, continues from next item
5. Repeat until complete

No guessing phases. No unexpected walls. Clean handoffs.

Alternative Solutions

Alternative Solutions

We built a working system using existing Claude Code primitives.

The Statusline Hack

Added one line to ~/.claude/statusline-command.sh:

echo "{\"ctx_pct\": $ctx_pct, \"tokens\": $current, \"max\": $size}" > "$HOME/.claude/context-status.json"

Now Claude can check its context:

cat ~/.claude/context-status.json
# Returns: {"ctx_pct": 68, "tokens": 136029, "max": 200000}

Two Skills Codifying the Workflow

/create-context-aware-plan - Creates plans with:

• Checklist-first structure (no phases)
• File references per checklist item (Read: lines)
• Implementation reference sections

/continue-context-aware-plan - Continues work with:

• Context monitoring verification
• Plan picker (presents available plans)
• Context number tracking (scans for highest ctx#, increments)
• Orchestrator model guidance
• Build verification after categories
• Clean handoff at 85%

Limitations of This Workaround

• Requires manual setup (statusline hack, skill installation)
• Relies on a hack that could break with updates
• Users must know to invoke the skills
• Not discoverable - users won't find this on their own

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Task: Implement 19 missing API handlers across multiple integration categories.

Without Context Awareness

Estimated requirements:

• ~2850 lines of generated code held in context
• Plus pattern files (~500 lines)
• Plus API reference files (~1000 lines)
• Plus conversation overhead
• Total: 150k+ tokens minimum

What would happen:

• Hit context wall mid-implementation
• Forced /compact or /new at inconvenient time
• Lost work or degraded quality
• Pre-guessing phase boundaries (and getting them wrong)

With Our Context-Aware System

A fresh Claude Code instance with zero prior context:

1. Invoked /continue-context-aware-plan
2. Skill verified context monitoring worked (read JSON file)
3. Presented plan picker, user selected the handler plan
4. Determined this was context 1 (no existing ctx# markers)
5. Read pattern files for understanding (not implementation)
6. Delegated to agents: "Create these handlers following pattern in X"
7. Agents worked in isolated context, returned summaries
8. Main context received: "Created HandlerA, HandlerB" (~20 lines, not ~300 lines of code)
9. Marked checklist items [x] (ctx1)
10. Checked context after each agent batch
11. Verified build after completing each category
12. Completed all 19 handlers at 69% context

Why It Worked

The orchestrator model:

• Main context holds: Plan understanding, pattern knowledge, agent summaries
• Agents hold: Actual implementation work (isolated context)
• Summaries cross the boundary: ~20 lines per batch instead of full code

Key insight: Understanding stays in main context. Implementation lives in agent context. Only summaries cross the boundary.

Generated Code Quality

Reviewed all 19 handlers:

• Consistent structure across all handlers
• Correct auth formats for each integration type
• Proper error handling with specific exception types
• Good logging, timeout handling, disposal patterns
• Build passing with 0 warnings, 0 errors

Additional Context

What Would Make This Native

1. Expose context percentage to Claude - The data already exists (statusline receives it). This is trivial to implement.

1. Add orchestrator pattern to system prompt - Guidance for large tasks: "delegate implementation to agents, keep main context for understanding"

1. Built-in plan continuation - Plan picker, context tracking, file references per item

The Pieces Already Exist

Anthropic built:

• Statusline with context data
• Agents with isolated context
• Plan mode
• Skills system

We just connected them. The statusline hack is 1 line of bash. The skills are ~100 lines each of markdown.

Attached Files

• create-context-aware-plan/SKILL.md - The plan creation skill
• continue-context-aware-plan/SKILL.md - The plan continuation skill

Note on Multi-Context Handoffs

Ironically, the orchestrator pattern was so efficient that we couldn't get it to need a handoff during testing - 19 handlers completed at 69% context. The handoff mechanism (plan picker, context number detection, checklist continuation) is mechanically simple and the least risky part of the system. The real value is the context visibility and orchestrator guidance that prevents needing handoffs in the first place.

Summary

The individual pieces exist. The combination into a self-regulating workflow isn't documented or native.