> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents and subagents

> Named configurations for how the CLI behaves, the tool categories they grant, and the subagents the main agent delegates to

An agent is a named configuration for how Cortex should behave: which model, how much reasoning, and which tools it is allowed to touch. Cortex ships a few and you can add your own. A **subagent** is an agent the main one delegates to, so a long job can be split into pieces that report back.

This page covers the agents the CLI ships with, the commands for listing and creating them, the fields in an agent file, the six tool categories, where agent files are found, how to select one for a run, and what delegation to a subagent does and does not allow.

## The agents that ship with the CLI

| Agent      | Kind     | Behaviour                                                      |
| ---------- | -------- | -------------------------------------------------------------- |
| `build`    | Primary  | Full access. The default working agent                         |
| `plan`     | Primary  | Read-only. Investigates and proposes without changing anything |
| `explore`  | Subagent | Read-only investigation, capped at 15 steps                    |
| `general`  | Subagent | General-purpose worker. Cannot delegate further                |
| `research` | Subagent | Read-only research                                             |
| `title`    | Primary  | Names sessions. Uses the small model                           |
| `summary`  | Primary  | Summarises sessions. Uses the small model                      |

`title` and `summary` are internal housekeeping; you will not normally select them by hand.

<Note>
  An agent is not a mode. The `plan` agent is a configuration that happens to be read-only, while Plan mode is a lock on the whole session that holds whichever agent you are using. See [Modes and permissions](/cli/modes-and-permissions).
</Note>

## Manage agents

```bash theme={null}
cortex agent list                 # everything available
cortex agent list --primary       # only primary agents
cortex agent list --subagents     # only subagents
cortex agent list --json
cortex agent show <name>
cortex agent create               # interactive
cortex agent create --generate "reviews Rust for concurrency bugs"
cortex agent edit <name>          # opens $EDITOR
cortex agent copy <source> <dest>
cortex agent export <name> -o agent.md
cortex agent install <name>
cortex agent remove <name>
```

Inside a session, `/agents` lists and manages them and `/delegates` covers subagents. `cortex agent install` pulls a definition from a registry; run `cortex agent install --help` on your build to see which sources it accepts.

## Write an agent

An agent is a markdown file with YAML frontmatter. The body is the agent's system prompt.

```markdown theme={null}
---
name: reviewer
description: Reviews a change for correctness and concurrency bugs
model: inherit
reasoning_effort: high
tools: read-only
max_steps: 40
---

You review code. Read the change, then report the problems you are confident
about, most serious first. Do not edit files and do not run commands.
```

| Field               | Type                      | Notes                                                                  |
| ------------------- | ------------------------- | ---------------------------------------------------------------------- |
| `name`              | string                    | How the agent is selected                                              |
| `description`       | string                    | Shown in `cortex agent list`                                           |
| `model`             | string                    | A model id, or `inherit` to use the session's model. Default `inherit` |
| `reasoning_effort`  | `low` / `medium` / `high` | How hard the model thinks                                              |
| `tools`             | category or list          | A category name, or an explicit list of tool names                     |
| `temperature`       | number                    |                                                                        |
| `max_steps`         | integer                   | Cap on tool-calling steps                                              |
| `color`             | string                    | Colour used in the session view                                        |
| `hidden`            | bool                      | Hide from the default listing                                          |
| `omit_instructions` | list                      | Instruction documents this agent skips                                 |

### The six tool categories

| Category    | Grants                           |
| ----------- | -------------------------------- |
| `read-only` | `Read`, `LS`, `Grep`, `Glob`     |
| `edit`      | `Create`, `Edit`, `ApplyPatch`   |
| `execute`   | `Execute`                        |
| `web`       | `WebSearch`, `FetchUrl`          |
| `mcp`       | Tools from connected MCP servers |
| `all`       | The full built-in set            |

`tools` takes either a category name or an explicit list of tool names, and an explicit list is exact. The names are case-sensitive: see [Tools the agent uses](/cli/tools).

### Where agent files are found

Searched in this order, and the first definition of a name wins:

1. `<project>/.agents/*.md`
2. `<project>/.agent/*.md`
3. `<project>/.cortex/agents/*.md`
4. `~/.cortex/agents/*.md`
5. `~/.config/cortex/agents/*.md`

Project agents therefore override personal ones, which is what you want when a repository has house rules.

## Select an agent

```bash theme={null}
cortex run --agent reviewer "review the last commit"
cortex --config current_agent=reviewer
```

```toml theme={null}
# config.toml
current_agent = "reviewer"
```

In a prompt, `@name` mentions an agent directly:

```
> @reviewer take a look at src/auth before I push this
```

<Warning>
  `@` is also the file-reference sigil in the composer, so `@src/main.rs` and `@reviewer` are typed the same way. When a name could be read either way, pass `--agent` or set `current_agent` instead of relying on the mention.
</Warning>

## Instruction documents an agent skips

Agents read the repository's instruction documents. The chain is your home directory, then the repository root `AGENTS.md`, then any `AGENTS.md` between the root and your working directory. `cortex init` writes one for a repository that does not have it yet.

`omit_instructions` lets an agent skip part of that chain for one run:

| Scope     | Documents                                                               |
| --------- | ----------------------------------------------------------------------- |
| `user`    | The `AGENTS.md` in your Cortex home directory                           |
| `project` | The repository-root `AGENTS.md`                                         |
| `local`   | `AGENTS.md` files between the repository root and the working directory |
| `managed` | Organization policy. Never omitted                                      |

Omission is opt-in and applies to that run only. A skipped document is never opened, so it cannot reach the prompt by another path. Organization-managed policy always loads: a request that names `managed` is accepted, recorded, and ignored, and the same is true when the main agent passes `omit_instructions` to the `Task` tool. An unknown scope name is an error rather than a silent no-op, so a typo cannot omit the wrong documents. Every omission is recorded in the audit journal under your Cortex home directory, described in [Permission policy](/cli/policy).

## Delegation and subagents

Subagents are agents the main agent delegates to, through the `Task` tool. A task runs in one of three roles, `explore`, `plan` or `worker`, and reports back when it finishes.

Delegated work is constrained: a child task cannot spawn its own children, ask you questions directly, or message you. Everything flows back through the parent. `/tasks` shows what is running in the background.

Three overlapping lists are worth keeping straight:

* **Three roles** a task can run in: `explore`, `plan`, `worker`.
* **Eight built-in subagent types**: `code`, `research`, `refactor`, `test`, `documentation`, `security`, `architect` and `reviewer`, plus any custom agent you define.
* **Seven built-in agents**, in the table at the top of this page.

## Related

* [Tools the agent uses](/cli/tools)
* [Skills in the CLI](/cli/skills)
* [Modes and permissions](/cli/modes-and-permissions)
* [Permission policy](/cli/policy)
* [Headless and one-shot runs](/cli/headless)