Skip to main content
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

title and summary are internal housekeeping; you will not normally select them by hand.
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.

​
Manage agents

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.

​
The six tool categories

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.

​
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

In a prompt, @name mentions an agent directly:
@ 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.

​
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: 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.

​
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.