[FEATURE] Agent Aliases/Nicknames

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

Built-in agent types (like rails-architect, rails-controller-engineer, etc.) cannot be referenced by custom names or aliases. Users must use the exact built-in agent type names, which may not align with team naming conventions or preferences. There's currently no way to add nicknames to existing agent types without creating duplicate custom subagent definitions.

The default names are defined by library owners.

Proposed Solution

Add a nickname/alias configuration option for agents that allows users to reference built-in agent types by custom names.

---
Implementation could be through a nickname field in agent configuration:

{
"agent_type": "rails-architect",
"nickname": "viper",
"description": "Rails Architecture Expert"
}

Users could then invoke the agent with either:

• @rails-architect (original name)
• @viper (nickname)

Both would reference the same built-in agent type with all its capabilities intact.

---

Alternative Solutions

Add an alias mapping configuration in settings:

{
"agent_aliases": {
"viper": "rails-architect",
"db-wizard": "rails-model-engineer",
"frontend-ninja": "rails-hotwire-engineer"
}
}

This would be a global setting that maps custom names to built-in agent types. The mapping could be stored in .claude/settings.json or user-level settings.

Priority

Low - Nice to have

Feature Category

Configuration and settings

Use Case Example

Scenario 1: Team naming conventionsI want to refer to @rails-architect as @viper to match our team's internal naming system without losing the built-in agent's capabilities.

Scenario 2: Shorter names for efficiencyInstead of typing @rails-hotwire-engineer, I'd prefer @turbo for faster invocation.

Scenario 3: Multi-project consistencyMaintain consistent agent naming across multiple projects without duplicating agent definitions in each .claude/agents/ directory.

Benefits:

• Personalized naming that fits team culture
• Shorter, memorable names for frequently-used agents
• No need to duplicate built-in agent configurations
• Backwards compatible (original names continue to work)

Current workaround:Creating custom subagents with desired names, but this duplicates configuration and requires manual maintenance to keep in sync with built-in agent improvements.

Additional Context

Similar features in other tools:

• Git: Supports aliases via git config (e.g., git co → git checkout)
• Bash/Zsh: Built-in alias command for command shortcuts
• VSCode: Extension marketplace allows custom keybindings and command names
• Slack: Allows custom slash commands and bot name customization

Technical considerations:

• Alias resolution should happen before agent invocation
• Original agent type names must remain functional for backwards compatibility
• Aliases should be case-insensitive (like current @agent mentions)
• Conflicts should be handled gracefully (e.g., custom agent named "viper" vs. alias "viper")
• Priority order: custom subagents > aliases > built-in names

User experience improvements:

• Reduces cognitive load when working with multiple specialized agents
• Allows teams to adopt Claude Code without disrupting existing workflows
• Makes onboarding easier by using familiar terminology
• Enables more natural conversation flow with shorter agent names

Potential implementation locations:

1. Project-level: .claude/settings.json (team-wide aliases)
2. User-level: ~/.claude/settings.json (personal preferences)
3. Per-agent: .claude/agents/viper.json → { "extends": "rails-architect" }

Edge cases to consider:

• What happens if alias conflicts with existing built-in agent name?
• Should aliases work in nested agent invocations?
• Can one built-in agent have multiple aliases?
• Should aliases be listed when running /agents command?

Related feature that would complement this:

• Agent groups: @rails-team could invoke multiple related agents
• Agent inheritance: Custom agents could extend built-in ones while keeping updates

Current behavior:

• Mentioning @viper when no such agent exists results in generic task delegation
• No way to customize or override built-in agent names
• Adding a "nickname" field to custom agents in .claude/agents/ currently has no effect

Environment:

• Observed in Claude Code CLI
• Affects all platforms (Linux, macOS, Windows)
• Relevant to both individual users and teams using version-controlled .claude/ directories