[BUG] [BUG] Agents don't auto-load without restart - breaks user workflow

Resolved 💬 3 comments Opened Aug 14, 2025 by tbardale Closed Aug 15, 2025

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:

  1. Confusing User Experience: Users try to use newly created agents and get no response
  2. Broken Workflow: Forces interruption of active work sessions
  3. Discovery Time: Takes 4-5 iterations for users to understand the restart requirement
  4. Poor Adoption: Users may abandon agent creation due to friction

## Steps to Reproduce

  1. Create a new agent file in .claude/agents/new-agent.md
  2. Try to use the agent with Task(subagent_type="new-agent", ...)
  3. Agent is not recognized/available
  4. User must /exit and run claude --continue to 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:

  1. Type '/exit'
  2. 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-agents command for manual refresh
  • Show agent status in /agents command (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:

  • bug
  • ux-improvement
  • enhancement
  • area: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.

View original on GitHub ↗

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