kilocode/packages/kilo-docs/pages/code-with-ai/agents/using-agents.md

title, description

title	description
Using Agents	Understanding and using different agents in Kilo Code

Using Agents

Agents in Kilo Code are specialized personas that tailor the assistant's behavior to your current task. Each agent offers different capabilities, expertise, and access levels to help you accomplish specific goals.

{% callout type="info" %} The VSCode (Legacy) extension calls these modes instead of agents. The concept is the same — specialized personas with distinct tool access and behavior. {% /callout %}

Why Use Different Agents?

• Task specialization: Get precisely the type of assistance you need for your current task
• Safety controls: Prevent unintended file modifications when focusing on planning or learning
• Focused interactions: Receive responses optimized for your current activity
• Workflow optimization: Seamlessly transition between planning, implementing, debugging, and learning

Switching Agents

{% tabs %} {% tab label="VSCode" %}

There are several ways to switch agents:

• Dropdown menu: Click the agent selector in the sidebar to switch between agents.
• Slash commands: Type /agents in the chat input to open the agent picker.
• Keyboard shortcut: Press Cmd+. (macOS) or Ctrl+. (Windows/Linux) to cycle through available agents. Add Shift to cycle in reverse.

{% /tab %} {% tab label="CLI" %}

There are several ways to switch agents:

• Cycle agents: Press Tab to cycle forward through agents, or Shift+Tab to cycle backward.
• Agent picker: Press Ctrl+X a (leader key + a) to open the full agent list.
• Slash commands: Type /agents in the chat input to open the agent picker.
• Config file: Set the default_agent key in your configuration to change the default agent on startup.

{% /tab %} {% tab label="VSCode (Legacy)" %}

{% youtube url="https://youtu.be/cS4vQfX528w" caption="Explaining the different modes in Kilo Code" /%}

Four ways to switch modes:

1. Dropdown menu: Click the selector to the left of the chat input

   {% image src="/docs/img/modes/modes.png" alt="Using the dropdown menu to switch modes" width="400" /%}

2. Slash command: Type /agents or /modes to list modes and switch. Type /newtask to create a new task, or /smol to condense your context window.

   {% image src="/docs/img/modes/modes-1.png" alt="Using slash commands to switch modes" width="400" /%}

Understanding /newtask vs /smol

Users often confuse /newtask and /smol. Here's the key difference:

Command	Purpose	When to Use
/newtask	Creates a new task with context from the current task	When you want to start something new while carrying over context
/smol	Condenses your current context window	When your conversation is getting too long and you want to summarize it

3. Toggle command/Keyboard shortcut: Use the keyboard shortcut below, applicable to your operating system. Each press cycles through the available modes in sequence, wrapping back to the first mode after reaching the end.

   Operating System	Shortcut
   macOS	⌘ + .
   Windows	Ctrl + .
   Linux	Ctrl + .

You can hold shift to move backwards through the list of modes, for example ⌘ + shift + on macOS.

4. Accept suggestions: Click on mode switch suggestions that Kilo Code offers when appropriate

   {% image src="/docs/img/modes/modes-2.png" alt="Accepting a mode switch suggestion from Kilo Code" width="400" /%}

{% /tab %} {% /tabs %}

Built-in Agents

{% tabs %} {% tab label="VSCode" %}

code (Default)

Aspect	Details
Description	A skilled software engineer with expertise in programming languages, design patterns, and best practices
Tool Access	Full access to all tools: read, edit, glob, grep, bash, task, webfetch, plus tools from MCP servers
Ideal For	Writing code, implementing features, debugging, and general development
Special Features	No tool restrictions — full flexibility for all coding tasks

ask

Aspect	Details
Description	A knowledgeable technical assistant focused on answering questions without changing your codebase
Tool Access	Read-only tools only (cannot edit files or run commands)
Ideal For	Code explanation, concept exploration, and technical learning
Special Features	Optimized for informative responses without modifying your project

plan

Aspect	Details
Description	An experienced technical leader and planner who helps design systems and create implementation plans
Tool Access	Read-only tools plus restricted file editing (plan files in .kilo/plans/ only)
Ideal For	System design, high-level planning, and architecture discussions
Special Features	Similar to the legacy extension's "Architect" mode, with a planning-focused approach

debug

Aspect	Details
Description	An expert problem solver specializing in systematic troubleshooting and diagnostics
Tool Access	Full access to all tools
Ideal For	Tracking down bugs, diagnosing errors, and resolving complex issues
Special Features	Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues

orchestrator (Deprecated)

Aspect	Details
Description	A strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized agents
Tool Access	Limited access to create new tasks and coordinate workflows
Ideal For	Breaking down complex projects into manageable subtasks assigned to specialized agents
Special Features	Delegates work to other agents; also has access to the explore subagent for codebase exploration

{% callout type="warning" %} Orchestrator is deprecated and will be removed in a future release. Agents with full tool access (Code, Plan, Debug) now support subagents natively — there's no need for a dedicated orchestrator. See Orchestrator Mode (Deprecated) for migration details. {% /callout %}

{% callout type="info" %} The VSCode extension and CLI do not include a built-in Review agent. Code review workflows can be handled by the code agent or via custom agent configurations. {% /callout %}

{% /tab %} {% tab label="CLI" %}

code (Default)

Aspect	Details
Description	A skilled software engineer with expertise in programming languages, design patterns, and best practices
Tool Access	Full access to all tools: read, edit, glob, grep, bash, task, webfetch, plus tools from MCP servers
Ideal For	Writing code, implementing features, debugging, and general development
Special Features	No tool restrictions — full flexibility for all coding tasks

ask

Aspect	Details
Description	A knowledgeable technical assistant focused on answering questions without changing your codebase
Tool Access	Read-only tools only (cannot edit files or run commands)
Ideal For	Code explanation, concept exploration, and technical learning
Special Features	Optimized for informative responses without modifying your project

plan

Aspect	Details
Description	An experienced technical leader and planner who helps design systems and create implementation plans
Tool Access	Read-only tools plus restricted file editing (plan files in .kilo/plans/ only)
Ideal For	System design, high-level planning, and architecture discussions
Special Features	Similar to the legacy extension's "Architect" mode, with a planning-focused approach

debug

Aspect	Details
Description	An expert problem solver specializing in systematic troubleshooting and diagnostics
Tool Access	Full access to all tools
Ideal For	Tracking down bugs, diagnosing errors, and resolving complex issues
Special Features	Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues

orchestrator (Deprecated)

Aspect	Details
Description	A strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized agents
Tool Access	Limited access to create new tasks and coordinate workflows
Ideal For	Breaking down complex projects into manageable subtasks assigned to specialized agents
Special Features	Delegates work to other agents; also has access to the explore subagent for codebase exploration

{% callout type="warning" %} Orchestrator is deprecated and will be removed in a future release. Agents with full tool access (Code, Plan, Debug) now support subagents natively — there's no need for a dedicated orchestrator. See Orchestrator Mode (Deprecated) for migration details. {% /callout %}

{% callout type="info" %} The VSCode extension and CLI do not include a built-in Review agent. Code review workflows can be handled by the code agent or via custom agent configurations. {% /callout %}

{% /tab %} {% tab label="VSCode (Legacy)" %}

Code Mode (Default)

Aspect	Details
Description	A skilled software engineer with expertise in programming languages, design patterns, and best practices
Tool Access	Full access to all tool groups: read, edit, browser, command, mcp
Ideal For	Writing code, implementing features, debugging, and general development
Special Features	No tool restrictions—full flexibility for all coding tasks

Ask Mode

Aspect	Details
Description	A knowledgeable technical assistant focused on answering questions without changing your codebase
Tool Access	Limited access: read, browser, mcp only (cannot edit files or run commands)
Ideal For	Code explanation, concept exploration, and technical learning
Special Features	Optimized for informative responses without modifying your project

Architect Mode

Aspect	Details
Description	An experienced technical leader and planner who helps design systems and create implementation plans
Tool Access	Access to read, browser, mcp, and restricted edit (markdown files only)
Ideal For	System design, high-level planning, and architecture discussions
Special Features	Follows a structured approach from information gathering to detailed planning

Debug Mode

Aspect	Details
Description	An expert problem solver specializing in systematic troubleshooting and diagnostics
Tool Access	Full access to all tool groups: read, edit, browser, command, mcp
Ideal For	Tracking down bugs, diagnosing errors, and resolving complex issues
Special Features	Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues

{% callout type="tip" %} Keep debugging separate from main tasks: When using Debug mode, ask Kilo to "start a new task in Debug mode with all of the necessary context needed to figure out X" so that the debugging process uses its own context window and doesn't pollute the main task. {% /callout %}

Orchestrator Mode

Aspect	Details
Description	A strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes
Tool Access	Limited access to create new tasks and coordinate workflows
Ideal For	Breaking down complex projects into manageable subtasks assigned to specialized modes
Special Features	Uses the new_task tool to delegate work to other modes

Review Mode

Aspect	Details
Description	An expert code reviewer specializing in analyzing changes to provide structured feedback on quality, security, and best practices
Tool Access	Access to read, browser, mcp, and when permitted, edit
Ideal For	Catching issues early, enforcing code standards, accelerating PR turnaround
Special Features	Code review before committing, surfacing feedback across performance, security, style, and test coverage

{% /tab %} {% /tabs %}

Custom Agents

Create your own specialized assistants by defining tool access, file permissions, and behavior instructions. Custom agents help enforce team standards or create purpose-specific assistants. See Custom Modes documentation for setup instructions.