[BUG] [BUG] Agents don't auto-load without restart - breaks user workflow
Summary
New agents created in .claude/agents/ directory are not automatically loaded by Claude Code, requiring users to restart the entire session with /exit and
claude --continue. This creates a frustrating user experience and breaks the thought process flow.
## Problem Description
When users create new agent definition files in .claude/agents/, the agents are not available until Claude Code is restarted. This leads to:
- Confusing User Experience: Users try to use newly created agents and get no response
- Broken Workflow: Forces interruption of active work sessions
- Discovery Time: Takes 4-5 iterations for users to understand the restart requirement
- Poor Adoption: Users may abandon agent creation due to friction
## Steps to Reproduce
- Create a new agent file in
.claude/agents/new-agent.md - Try to use the agent with
Task(subagent_type="new-agent", ...) - Agent is not recognized/available
- User must
/exitand runclaude --continueto reload agents
## Expected Behavior
Option A (Preferred): Agents auto-load when new files are detected
Option B (Minimum): Clear user feedback when agents need restart
## Proposed Solutions
### Immediate Fix (Low Effort)
When an unknown agent is referenced, display helpful message:
⚠️ Agent 'new-agent' not found.
💡 If you just created this agent, restart Claude Code:
- Type '/exit'
- Run 'claude --continue'
Available agents: [list current agents]
### Better Solution (Medium Effort)
Implement hot-reloading for agent definitions:
- Watch
.claude/agents/directory for changes - Automatically reload agent definitions when files are added/modified
- Show confirmation:
✅ Loaded new agent: 'new-agent'
### Ideal Solution (Higher Effort)
- Hot-reload agents automatically
- Provide
/reload-agentscommand for manual refresh - Show agent status in
/agentscommand (loaded/pending restart)
## Impact
- User Frustration: High - breaks workflow and confuses users
- Adoption Barrier: Medium - reduces willingness to create custom agents
- Support Burden: Medium - likely generates support questions
## Workaround
Users must restart Claude Code session after creating new agents:
```bash
/exit
claude --continue
Environment
- Platform: Cross-platform issue
- Component: Agent loading system
- User Type: All users creating custom agents
Priority Suggestion
Medium-High - Affects user experience and workflow but has workaround
### Step 4: Add Labels (if available)
Select these labels if they exist:
bugux-improvementenhancementarea:core
Note
- Complete issue is structured by claude-code given problem statement- also explained how to open ( would be more happy if I can create it from claude-code [ will yet to expire gh cli integration ]
this note is written by hand.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗