Kode-cli/docs/agents-system.md

Agent Configuration System

Overview

Kode's Agent system allows you to create specialized AI agents with predefined configurations, tools, and prompts. This enables more efficient task execution by using purpose-built agents for specific types of work.

New in this version: Use @run-agent-name for intelligent delegation with auto-completion support.

Features

• Dynamic Agent Loading: Agents are loaded from configuration files at runtime
• Five-tier Priority System: Built-in < .claude (user) < .kode (user) < .claude (project) < .kode (project)
• Hot Reload: Agent files monitored via Node.js fs.watch with cache invalidation
• Tool Restrictions: Limit agents to specific tools for security and focus
• Model Selection: Each agent can specify its preferred AI model
• Interactive Management: Use /agents command for graphical management

Quick Start

Using Pre-configured Agents

Kode has one built-in agent:

@run-agent-general-purpose Find all TypeScript test files
@run-agent-my-custom-agent Implement a new user authentication feature

Managing Agents

Use the /agents command in the Kode REPL to manage agents:

kode
> /agents

This opens an interactive UI where you can:

• View all available agents
• Create new agents
• Edit existing agents
• Delete custom agents

Keyboard shortcuts:

• c - Create new agent
• r - Reload agents
• d - Delete selected agent (when viewing)
• q or Esc - Exit

Agent Configuration

File Structure

Agents are defined as Markdown files with YAML frontmatter:

---
name: agent-name
description: "When to use this agent"
tools: ["Tool1", "Tool2", "Tool3"]  # or "*" for all tools
model_name: model-name  # optional (preferred over deprecated 'model' field)
---

System prompt content goes here...

Note: Use model_name to specify the AI model. The deprecated model field is ignored.

Configuration Locations

Agents can be defined at five levels with priority order (later overrides earlier):

1. Built-in (lowest priority)

   • Provided with Kode
   • Cannot be modified

2. Claude User (~/.claude/agents/)

   • Claude Code compatible user-level agents
   • Personal agents available across all projects

3. Kode User (~/.kode/agents/)

   • Kode-specific user-level agents
   • Overrides Claude user agents with same name
   • Create with /agents command or manually

4. Claude Project (./.claude/agents/)

   • Claude Code compatible project-specific agents
   • Overrides user-level agents

5. Kode Project (./.kode/agents/)

   • Kode-specific project agents
   • Highest priority, overrides all others

Example: Creating a Custom Agent

1. Manual Creation

Create a file ~/.kode/agents/api-designer.md:

---
name: api-designer
description: "Designs RESTful APIs and GraphQL schemas with best practices"
tools: ["FileRead", "FileWrite", "Grep"]
model_name: reasoning
---

You are an API design specialist. Your expertise includes:

- Designing RESTful APIs following OpenAPI specifications
- Creating GraphQL schemas with efficient resolvers
- Implementing proper authentication and authorization
- Ensuring API versioning and backward compatibility
- Writing comprehensive API documentation

Design principles:
- Follow REST best practices (proper HTTP verbs, status codes, etc.)
- Design for scalability and performance
- Include proper error handling and validation
- Consider rate limiting and caching strategies
- Maintain consistency across endpoints

2. Using /agents Command

1. Run kode to start the REPL
2. Type /agents
3. Press c to create
4. Follow the prompts:
   • Enter agent name
   • Describe when to use it
   • Specify allowed tools
   • Optionally specify a model
   • Write the system prompt

Advanced Usage

Tool Restrictions

tools: ["FileRead", "Grep", "Glob"]  # Specific tools
tools: ["*"]                         # All tools (default)

Model Selection

Specify which AI model the agent should use:

model_name: quick      # Fast responses for simple tasks
model_name: main       # Default model for general tasks  
model_name: reasoning  # Complex analysis and design

Available Built-in Agents

general-purpose

• Use for: General research, complex multi-step tasks
• Tools: All tools
• Model: task (default)

Note: This is currently the only built-in agent. Create custom agents using the /agents command or by adding configuration files.

Custom Agents

Create your own agents in the appropriate directory:

mkdir -p .kode/agents    # Project-specific
mkdir -p ~/.kode/agents  # User-wide

Best Practices

1. Agent Naming: Use descriptive, action-oriented names (e.g., test-writer, api-designer)

2. Tool Selection: Only include tools the agent actually needs

3. System Prompts: Be specific about the agent's role and guidelines

4. Model Choice:

   • Use quick for simple, fast operations
   • Use main for general coding tasks
   • Use reasoning for complex analysis

5. Organization:

   • Keep user agents for personal workflows
   • Keep project agents for team-shared configurations

Troubleshooting

Agents not loading?

• Check file permissions in ~/.kode/agents/ or ./.kode/agents/
• Ensure YAML frontmatter is valid
• Use /agents command and press r to reload

Agent not working as expected?

• Verify the tools list includes necessary tools
• Check the system prompt is clear and specific
• Test with verbose mode to see actual prompts

Hot reload not working?

• File watcher requires proper file system events
• Try manual reload with /agents then r
• Restart Kode if needed

Integration with Task Tool

The agent system is integrated with Kode's Task tool:

// In your code or scripts
await TaskTool.call({
  description: "Search for patterns",
  prompt: "Find all instances of TODO comments",
  subagent_type: "general-purpose"
})

This allows programmatic use of agents in automation and scripts.

Future Enhancements

Planned improvements:

• Agent templates and inheritance
• Performance metrics per agent
• Agent composition (agents using other agents)
• Cloud-based agent sharing
• Agent versioning and rollback