[FEATURE] Dynamic/Lazy Agent Loading to Reduce Context Token Usage

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

supporting dynamic agent loading where:

• A registry agent queries available agents
• System loads only the needed agents into context on-demand
• Agents are unloaded when no longer needed

Problem

Currently, Claude Code loads all agent descriptions at startup and includes them in every prompt. With
multiple specialized agents, this causes significant token bloat that impacts performance.

Example: I have ~16.2k tokens of agent descriptions loaded, exceeding the 15k recommendation, even though
only 2-3 agents are typically needed for any given task.

## Current Limitations

• All agents load upfront regardless of whether they're needed
• Large agent collections consume context window unnecessarily
• Users must manually enable/disable agents via /agents between sessions
• No way to dynamically load agents based on task requirements

## Proposed Solution
Implement dynamic/lazy agent loading where:

1. Registry Agent Pattern: A lightweight "agent registry" agent that:

• Has minimal token footprint (~200-500 tokens)
• Knows available agents and their capabilities
• Analyzes the user's request to determine which agents are actually needed
• Loads only relevant agents into context on-demand

1. Runtime Agent Management:

• Agents loaded mid-conversation when needed
• Agents unloaded when task is complete
• Only active agents consume context tokens

## Benefits

• Dramatically reduced baseline token usage
• Better performance for users with large agent collections
• Ability to maintain extensive agent libraries without performance penalty
• More scalable agent ecosystem

## Alternative Approaches

• Agent groups/profiles that can be switched dynamically
• Token budget limits per agent suite
• Automatic agent pruning based on relevance scoring

## Use Case
I want 50+ specialized agents available but only load the 2-3 relevant ones per task, keeping my context usage
minimal.

Proposed Solution

I'd like to have hundreds of very specialized agents and commands available to claude code without having to load them all into context. I could move them to another folder and have a reference agent, but i'd prefer there to be some kind of default functionality; such that claude will look to the registry agent similar to how it looks to claude.md first.

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_