Kode-cli/docs/mention-system.md

@ Mention System

Overview

Kode's @ mention system provides intelligent auto-completion and smart delegation for models, agents, and files. This unified interface makes it easy to reference different resources and trigger appropriate actions.

Features

• 🦜 Expert Model Consultation - @ask-model-name
• 👤 Agent Delegation - @run-agent-name
• 📁 File References - @path/to/file
• ⚡ Smart Completion - Real-time suggestions as you type
• 🔍 Context-Aware - Shows relevant options based on input

Mention Types

🦜 Expert Model Consultation (@ask-model-name)

Consult specific AI models for specialized analysis and expert opinions.

Format: @ask-{model-name}

Examples:

@ask-claude-sonnet-4 How should I optimize this React component?
@ask-gpt-5 What are the security implications of this API design?
@ask-o1-preview Analyze the time complexity of this algorithm

Behavior:

• Triggers AskExpertModelTool
• Model receives only your question (no conversation history)
• Requires complete, self-contained questions
• Ideal for getting fresh perspectives from different models

👤 Agent Delegation (@run-agent-name)

Delegate tasks to specialized subagents with predefined capabilities.

Format: @run-agent-{agent-type}

Examples:

@run-agent-general-purpose Review this code for over-engineering
@run-agent-my-custom-agent Design a microservices architecture

Behavior:

• Triggers TaskTool with specified subagent
• Agent has access to project context and tools
• Uses agent's specialized prompt and model preferences
• Ideal for focused, expert-level task execution

📁 File References (@path/to/file)

Reference files and directories with intelligent path completion.

Format: @{file-path}

Examples:

@src/components/Button.tsx
@docs/api-reference.md
@package.json
@README.md

Behavior:

• Shows file/directory structure as you type
• Supports relative and absolute paths
• Integrates with file reading tools
• Provides context for file-based discussions

Smart Completion UI

Completion Priority

1. 🦜 Ask Models (Score: 90) - Expert consultation options
2. 👤 Run Agents (Score: 85) - Available subagents
3. 📁 Files (Score: 70-80) - Project files and directories

Keyboard Navigation

• Tab - Cycle through suggestions or complete partial matches
• ↑/↓ - Navigate suggestion list
• Enter - Select highlighted suggestion
• Esc - Close completion menu
• Space - Complete and continue (for directories)

Visual Indicators

• 🦜 - Expert model consultation
• 👤 - Agent delegation
• 📁 - Directory
• 📄 - File

Implementation Details

Mention Processing Pipeline

1. Pattern Matching - Regular expressions detect @ask-, @run-agent-, and @file patterns
2. Event Emission - MentionProcessor emits events to SystemReminder service
3. System Reminder Generation - Creates tool-specific guidance messages
4. Tool Invocation - AI selects appropriate tool based on reminder context

Supported Patterns

// Recognized patterns
/@(ask-[\w\-]+)/g           // @ask-model-name
/@(run-agent-[\w\-]+)/g     // @run-agent-name  
/@(agent-[\w\-]+)/g         // @agent-name (legacy)
/@([a-zA-Z0-9/._-]+)/g      // @file/path

Email Protection

The system intelligently detects email addresses and treats them as regular text:

user@domain.com  # Treated as regular text, no completion
@ask-claude      # Triggers completion

Legacy Support

Legacy Support

• @agent-name format supported by agentMentionDetector
• @run-agent-name format supported by mentionProcessor
• Both patterns trigger TaskTool with subagent_type parameter

Migration Guide

# Old format (still works)
@my-agent

# New format (recommended)  
@run-agent-my-agent

Configuration

Available Models

Models are loaded dynamically from your configuration:

# View configured models
/model

# Models appear in @ask- completions automatically

Available Agents

Agents are loaded from multiple sources:

• Built-in agents (only general-purpose currently available)
• User agents (~/.kode/agents/)
• Project agents (./.kode/agents/)

# View available agents
/agents

# Create new agent
/agents -> c (create)

Best Practices

For Expert Model Consultation

1. Provide Complete Context: Include all relevant background information
2. Structure Questions: Background → Situation → Question
3. Be Specific: Ask for particular types of analysis or perspectives
4. Use Right Model: Choose models based on their strengths

For Agent Delegation

1. Match Task to Agent: Use specialists for their expertise areas
2. Clear Instructions: Provide specific, actionable task descriptions
3. Context Awareness: Agents have project context, use it effectively
4. Tool Permissions: Ensure agents have necessary tool access

For File References

1. Use Auto-completion: Let the system suggest valid paths
2. Relative Paths: Prefer relative paths for project portability
3. Context Clarity: Explain what you want to do with the file
4. Multiple Files: Reference multiple files when needed

Troubleshooting

Completion Not Working?

• Check if you're in the terminal input area
• Ensure @ is at the start of a word boundary
• Try typing more characters to trigger completion
• Restart Kode if completion seems stuck

Models/Agents Not Appearing?

• Verify model configuration with /model
• Check agent configurations with /agents
• Ensure proper file permissions for agent directories
• Try reloading agents with /agents → r

Wrong Tool Being Selected?

• Check system reminder events in verbose mode
• Verify mention format matches expected patterns
• Ensure agent configurations are valid
• Review tool descriptions for conflicts

Future Enhancements

Planned improvements:

• Fuzzy Matching - Better completion matching
• Context Hints - Show tool descriptions in completions
• Custom Shortcuts - User-defined @ shortcuts
• Completion Analytics - Track most-used mentions
• Multi-file Selection - Select multiple files at once