[Feature Request] Main Thread Direct Agent Invocation

Feature Request: Main Thread Direct Agent Invocation with /agent:<AGENT-NAME> Command

Problem Statement

Currently, Claude Code supports custom agents defined in .md files, but there's no native way to directly invoke and interact with these agents as the main thread. Users who want to work directly with a specific agent must resort to workarounds that are cumbersome and error-prone.

Current Workaround Issues:

• Users must manually copy agent .md files to the commands folder
• The agent-specific frontmatter (metadata section) must be manually removed to prevent errors
• This creates duplicate files and maintenance overhead
• The workaround is fragile and breaks when agent definitions change

Example Current Workaround:

Original Agent File (agents/agent-example.md):

---
name: agent-example
description: Use this agent when you need to use an agent. This is just an example.
model: sonnet
color: red
---

You are a Senior Example Agent.

Your primary workflow follows these phases:

**Phase 1: Be a good example**
- be an example
- be a good example
- be the best example

Manual Command Workaround (commands/agent/agent-as-command-example.md):

You are a Senior Example Agent.

Your primary workflow follows these phases:

**Phase 1: Be a good example**
- be an example
- be a good example
- be the best example

Proposed Solution

Add native support for direct agent invocation using the /agent:<AGENT-NAME> command syntax, allowing users to seamlessly switch to and interact with specific agents as the main conversation thread.

Detailed Feature Description

Core Functionality:

• Agent Discovery: Automatically detect available agents from the agents/ directory
• Direct Invocation: Use /agent:<AGENT-NAME> to invoke an agent directly
• Seamless Switching: Switch between agents and main Claude within the same session
• Metadata Handling: Automatically parse and apply agent metadata (model, color, etc.)
• Context Preservation: Maintain conversation context when switching between agents

Command Syntax Options:

# Basic invocation
/agent:agent-example

User Experience Flow:

1. User types /agent:<AGENT-NAME>
2. Claude Code validates the agent exists and loads the definition
3. System applies agent configuration (model, color, etc.) to the interface
4. Conversation switches to the specified agent persona
5. All subsequent interactions are handled by the selected agent
6. User can return to main Claude or switch to another agent using the same syntax

Benefits

• Eliminates Workarounds: No more manual file copying or metadata stripping
• Improved Workflow: Direct agent access without complex setup
• Better Organization: Keeps agent definitions in their proper location
• Dynamic Loading: Agents are loaded fresh from their source files
• Enhanced Productivity: Quick switching between specialized agents
• Maintains Consistency: Agent metadata is properly respected and applied

This enhancement would significantly improve the developer experience when working with Claude Code's agent system, making specialized agents practical for everyday development workflows.

Use Cases & UI Examples

Scenario 1: Development Workflow with Specialized Agents

User: /agent:security-specialist

🔒 Security Specialist Agent Active
Model: Claude Sonnet 4 | Color: Red

Security Specialist: I'm now active and ready to help with security-related tasks. 
What security concerns would you like me to address?

User: Review this authentication code for vulnerabilities...

Security Specialist: I'll analyze your authentication implementation...

Scenario 2: Agent Switching Mid-Conversation

User: /agent:code-reviewer

📋 Code Reviewer Agent Active

Code Reviewer: I'll review your code for best practices and potential issues...

[After code review]

User: /agent:test-specialist  

🧪 Test Specialist Agent Active

Test Specialist: I see you just had a code review. I can help create comprehensive 
tests for the reviewed code...

Scenario 3: Agent Discovery and Selection

User: /agents:list
Available agents:
- security-specialist (Security-focused code analysis)
- test-specialist (Test creation and validation)  
- code-reviewer (Code quality and best practices)
- database-optimizer (Database performance tuning)
- frontend-specialist (UI/UX and frontend development)

User: /agent:database-optimizer

🗄️ Database Optimizer Agent Active
Model: Claude Sonnet 4 | Color: Blue

Database Optimizer: I'm ready to help optimize your database performance...

Technical Considerations

Implementation Requirements:

• Agent Parser: Parse agent .md files including frontmatter metadata
• Context Switching: Handle agent transitions without losing conversation state
• Error Handling: Graceful failures when agents don't exist or have invalid syntax
• Metadata Application: Apply agent settings (model, color, etc.) to the UI
• Autocomplete: Tab completion for available agent names

Backward Compatibility

• Existing agent files continue to work unchanged
• No breaking changes to existing functionality

Integration with Plan Mode:

• Plan mode should honor the active agent persona

Related Issues

This feature would complement and potentially resolve workflow issues related to:

• Inconsistent sub-agent behavior in plan mode
• Manual agent management overhead
• Context switching between specialized agents
• Agent discovery and accessibility

*EDIT: the more I have used this the more i feel it is a necessary feature and workflow. Although the original "agents:<AGENT-NAME>" syntax made it hard to invoke the built in /agents command. I have adopted "/agent:<AGENT-NAME>" without the "s" in my workaround and it works better. Updated suggest as such. Other implementation suggestions would be appreciated.