Agents
Specialists with their own instructions, tools and model, which the main agent hands work to.
The main agent can hand part of a task to another agent: a reviewer, a test writer, a researcher. Each has its own instructions, tools and model. Open the Agents screen with /agents or ⇧⌘A: "Specialists the main agent can hand work to".
Built-in agents
| Agent | What it's for |
|---|---|
general-purpose | Researches complex questions, searches for files and content, and does multi-step tasks. |
researcher | Reads code and the web to answer a specific question, then reports the answer. It cannot edit anything. |
build, plan | The session agents behind Build and Plan. |
| Review parts | The agents that /review runs: context, security, quality, practices, custom rules and challenge. |
You can replace a built-in with your own version of the same name.
Make an agent
Choose New agent on the Agents screen. The screen groups agents as This project, Global, Built-in and Review.
| Field | What it does |
|---|---|
| Name | One word, like security-reviewer. You and the main agent call it @security-reviewer. |
| Description | The main agent reads this to decide when to delegate, so say when to use it. |
| Scope | This project (saved in the repo, shared with your team) or global (in every project you open). |
| Kind | The main agent hands work to a subagent. You pick a session agent to run a session as. |
| Context | Isolated starts from the task alone. Forked starts from the conversation so far. |
| Model | Same as the session, or any model from a provider you've connected. |
| Tools | All of the main agent's tools, or a subset. |
| System prompt | What it does, how to work and what to report back. |
Review agents also have Added instructions, and Replace the rubric entirely (advanced).
Agent files
An agent is a Markdown file with YAML front matter. The body is its system prompt. Project agents are in .koda/agents/. Global agents are in ~/.config/kc/agents/.
---
name: test-writer
description: Writes the tests a change needs and runs them. Use after an edit to a function that has no test.
tools: [read_file, query_code_graph, write_file, edit_file, shell]
context: fresh
mode: subagent
provider: deepseek
model: deepseek-chat
---
You write focused tests for the functions that changed…
| Key | Values |
|---|---|
name | Defaults to the file name. |
description | Needed for the main agent to delegate. |
tools | A list of tool names. |
context | fresh or conversation. |
mode | primary (session agent), subagent, or all. |
provider, model | Its own model. |
rubric | add or replace, for review agents. |
Watching delegation
A delegation shows in the transcript as a Delegate row, @agent: task, with the agent's own calls under it. Click the row to open the agent's run. Back to the main agent returns. The dock lists running agents with their activity, tokens and time. The inspector shows the delegation tree. Stop this subagent stops one agent.
An agent that the main agent starts cannot start more agents, so the work stays one level deep. A finished subagent stays open until the main agent closes it, so the main agent can send it more messages. Closing a subagent stops any commands that it left running.
Background subagents count toward Parallel autonomous tasks in Background work.