›_ Claude Code Issues
Claude Code Issues / #14867

[BUG]

Resolved 💬 3 comments Opened Dec 20, 2025 by Anthonysu798 Closed Dec 24, 2025

Preflight Checklist

  • [x] I have searched existing issues and this hasn't been reported yet
  • [x] This is a single bug report (please file separate reports for different bugs)
  • [x] I am using the latest version of Claude Code

What's Wrong?

Subagents Hit Context Limit Simultaneously in Parallel Execution

Summary

When Claude Code creates multiple subagents to parallelize work, all or most subagents simultaneously fill their context windows and halt with "Context low - Run /compact to compact & continue" errors. This requires manual intervention in each subagent to compact and resume, breaking the autonomous workflow and defeating the purpose of parallelization.

Environment

  • Tool: Claude Code
  • Feature: Parallel subagent execution
  • OS: macOS (likely affects all platforms)

Steps to Reproduce

  1. Start a complex task in Claude Code that triggers parallel subagent creation
  2. Claude Code spawns multiple subagents to parallelize the work
  3. Leave the subagents to execute autonomously
  4. Return to find all subagents have stopped with context limit errors

Expected Behavior

When using parallel subagents for autonomous work:

  • Subagents should automatically manage their context windows
  • If context becomes low, subagents should self-compact before hitting the limit
  • Parallel execution should complete without requiring manual intervention in each subagent
  • OR parent agent should be able to send compact commands to child subagents

Actual Behavior

  • Multiple subagents simultaneously hit context limits
  • Each subagent displays: "Context low - Run /compact to compact & continue"
  • Work halts across all subagents
  • User must manually:
  1. Navigate into each individual subagent
  2. Run /compact command in each one
  3. Tell each subagent to continue after compacting
  • This defeats the purpose of autonomous parallel execution

Current Workaround

Manually compact each subagent and resume:

# In each subagent:
/compact
# Then tell it to continue the work

Impact

  • Workflow Disruption: Autonomous parallel execution becomes supervised serial intervention
  • Time Loss: What should be "fire and forget" parallelization requires constant monitoring
  • Scalability: The more subagents spawned, the more manual work required
  • User Experience: Contradicts the promise of autonomous agents handling complex tasks

Suggested Solutions

Option 1: Auto-Compact (Preferred)

Subagents should automatically run /compact when context reaches a threshold (e.g., 85% full), similar to how the main agent handles context management.

Option 2: Parent-Child Context Management

The parent agent should be able to:

  • Monitor child subagent context levels
  • Send compact commands to subagents proactively
  • Resume subagents after compacting

Option 3: Context Budgeting

When spawning parallel subagents, allocate context budgets intelligently:

  • Estimate context needs per task
  • Spawn fewer subagents with larger context allowances
  • Pre-compact before spawning if needed

Option 4: User Notification + Bulk Action

If manual intervention is required:

  • Notify user once (not per subagent)
  • Provide command to compact all subagents: /compact-all-subagents
  • Auto-resume all subagents after compacting

Additional Context

This issue appears to be particularly problematic when:

  • Multiple subagents are working on code generation tasks
  • Tasks involve significant context accumulation (file reading, analysis)
  • Long-running parallel operations

The current behavior suggests subagents don't have the same autonomous context management capabilities as the main agent, which creates a significant usability gap in the parallel execution feature.

Related

  • Subagent context should be managed as autonomously as main agent context
  • Consider implementing proactive context management strategies for subagents
  • Parent agent should have visibility and control over child subagent state

---

Labels: bug, claude-code, subagents, context-management, UX
Priority: High (blocks autonomous parallel execution workflow)

What Should Happen?

Claude code should auto compact it's subagent automatically or something similar to that so the user don't need to manually run the compact command

Error Messages/Logs

Subagent Context low please run /compact & continue

Steps to Reproduce

Subagents Hit Context Limit Simultaneously in Parallel Execution

Summary

When Claude Code creates multiple subagents to parallelize work, all or most subagents simultaneously fill their context windows and halt with "Context low - Run /compact to compact & continue" errors. This requires manual intervention in each subagent to compact and resume, breaking the autonomous workflow and defeating the purpose of parallelization.

Environment

  • Tool: Claude Code
  • OS: macOS (likely affects all platforms)
  • Version: 2.0.74

Steps to Reproduce

Prerequisites

  • Claude Code installed and authenticated
  • A project directory (can be empty or existing)

Minimal Reproduction Case

1. Create a test project structure:

mkdir claude-subagent-context-test
cd claude-subagent-context-test
mkdir -p src/{components,utils,services}

2. Create a file that will require context-heavy analysis:

src/legacy-code.js (create a file with significant content - at least 500+ lines):

// Legacy code requiring refactoring - intentionally verbose
class UserService {
  constructor() {
    this.users = [];
    this.cache = new Map();
    this.listeners = [];
  }
  
  addUser(user) {
    // Add 50+ lines of complex logic here with nested conditions,
    // error handling, validation, caching, event emission, etc.
  }
  
  updateUser(id, updates) {
    // Add 50+ lines of complex logic here
  }
  
  deleteUser(id) {
    // Add 50+ lines of complex logic here
  }
  
  // Repeat similar patterns for 10+ methods
  // Include nested functions, callbacks, error handling
  // Make it realistically complex with ~500-1000 lines total
}

3. Start Claude Code:

claude-code

4. In Claude Code, provide this prompt:

I need you to refactor this legacy codebase by:
1. Analyzing src/legacy-code.js for code smells
2. Creating a modern TypeScript version with proper types
3. Writing comprehensive unit tests
4. Creating integration tests
5. Writing API documentation
6. Creating usage examples
7. Setting up error handling patterns
8. Adding logging and monitoring
9. Creating performance benchmarks
10. Writing migration guide from old to new code

Please work on these tasks in parallel using subagents.

5. Observe Claude Code's behavior:

  • Claude Code will identify this as parallelizable work
  • It will spawn 4-6 subagents (e.g., "refactor-subagent-1", "testing-subagent-2", etc.)
  • Each subagent will begin working autonomously

6. Wait 5-10 minutes without interaction

Expected Result

All subagents complete their tasks autonomously, with the parent agent coordinating and merging results.

Actual Result

After 5-10 minutes, check subagent status (look at subagent logs/output):

All or most subagents show:

Context low - Run /compact to compact & continue

Output stops with messages like:

[refactor-subagent-1] Context usage: 95% - Please run /compact
[testing-subagent-2] Context low - Run /compact to compact & continue  
[docs-subagent-3] Context low - Run /compact to compact & continue
[integration-subagent-4] Context low - Run /compact to compact & continue

To continue work, user must:

  1. Switch to subagent 1: (no clear command documented)
  2. Run /compact in subagent 1
  3. Tell it to continue: "please continue your work"
  4. Repeat for subagent 2, 3, 4... N

Alternative Minimal Reproduction

If the above doesn't trigger the issue, use a more aggressive approach:

Prompt:

Please create a complete full-stack application with:
- React frontend with 20+ components
- Node.js backend with REST API
- Database schema and migrations
- Authentication system
- Admin dashboard
- User dashboard  
- Email service integration
- Payment processing
- File upload handling
- Real-time notifications

Use parallel subagents to work on frontend, backend, database, and DevOps simultaneously.

This larger scope will more reliably cause context exhaustion across multiple subagents.

What Makes This Reproducible

The key factors that trigger simultaneous context exhaustion:

  1. Parallelization: 4+ subagents spawned
  2. Context-heavy tasks: Code analysis, generation, testing require reading/writing substantial content
  3. Time: ~5-10 minutes of autonomous operation
  4. No manual intervention: Letting subagents run independently

Impact

  • Workflow Disruption: Autonomous parallel execution becomes supervised serial intervention
  • Time Loss: What should be "fire and forget" parallelization requires constant monitoring
  • Scalability: The more subagents spawned, the more manual work required
  • User Experience: Contradicts the promise of autonomous agents handling complex tasks

Current Workaround Challenges

Problem: No documented way to navigate into subagent context

# These commands don't work:
/subagent refactor-subagent-1  # Not a valid command
/switch refactor-subagent-1     # Not a valid command
/focus refactor-subagent-1      # Not a valid command

What users have to do:

  • Unclear/undocumented process to access individual subagent shells
  • Or restart entire task and monitor constantly
  • Or abandon parallelization feature entirely

Suggested Solutions

Option 1: Auto-Compact (Preferred)

Subagents should automatically run /compact when context reaches a threshold (e.g., 85% full), similar to how the main agent handles context management.

Option 2: Parent-Child Context Management

The parent agent should be able to:

  • Monitor child subagent context levels
  • Send compact commands to subagents proactively
  • Resume subagents after compacting

Option 3: Context Budgeting

When spawning parallel subagents, allocate context budgets intelligently:

  • Estimate context needs per task
  • Spawn fewer subagents with larger context allowances
  • Pre-compact before spawning if needed

Option 4: User Notification + Bulk Action

If manual intervention is required:

  • Notify user once (not per subagent)
  • Provide command to compact all subagents: /compact-all-subagents
  • Auto-resume all subagents after compacting

Additional Context

This issue appears to be particularly problematic when:

  • Multiple subagents are working on code generation tasks
  • Tasks involve significant context accumulation (file reading, analysis)
  • Long-running parallel operations

The current behavior suggests subagents don't have the same autonomous context management capabilities as the main agent, which creates a significant usability gap in the parallel execution feature.

Related

  • Subagent context should be managed as autonomously as main agent context
  • Consider implementing proactive context management strategies for subagents
  • Parent agent should have visibility and control over child subagent state

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.74

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

_No response_

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗