Custom Agents

A subagent is a separate worker Command Code hands a task to. It runs in its own context window with its own tools, system prompt, and (optionally) its own model. Command Code can run several at once, so work like editing three modules can happen in parallel instead of one at a time.

Three built-in agents are always available: General, Explore, and Plan. You can add your own as Markdown files.

Quick start

The fastest way to make a subagent is to ask for one:

create a code-reviewer subagent that reviews diffs for bugs and security issues

Command Code writes the agent file for you. From then on it delegates to that agent when the task matches.

To manage agents yourself, run:

/agents

That's it for getting started. The rest of this page covers making agents by hand, how delegation works, and the full file reference.

Built-in agents

These ship with Command Code and are always available. They're read-only - you can't edit or delete them.

Agent	When it runs	Tools
General	The default when no other agent fits. Research and multi-step tasks.	All tools
Explore	Codebase search and understanding that touches many files.	Read-only: `read_file`, `read_directory`, `read_multiple_files`, `grep`
Plan	Designing an approach and weighing trade-offs.	`read_file`, `read_multiple_files`

When Command Code delegates without naming an agent, the task goes to General.

Creating an agent

Ask Command Code (recommended)

Describe the agent in plain language, as shown in Quick start. Command Code drafts the name, description, system prompt, and a sensible tool set, then saves the file. You review and adjust.

Choosing Create agents with Command Code in the /agents menu shows the same thing - it points you back to just asking:

 Create agents with Command Code

 Ask Command Code to create or update subagents for you, e.g.

   ‣ "create a code-reviewer subagent that reviews diffs for bugs"
   ‣ "make a changelog agent that uses a fast model"

 Or edit the files directly:

   • .commandcode/agents/    (this project)
   • ~/.commandcode/agents/  (all projects)

 Docs: https://commandcode.ai/docs/core-concepts/custom-agents

 Press Enter to go back and just ask

The /agents manager

Run /agents to open the manager. It lists two create actions, your custom agents grouped by scope, and the read-only defaults.

 Agents (2 agents)

   1. Create agents with Command Code (recommended)
   2. Create manually

   User agents
 > changelog-writer
   release-notes

   Project agents
   code-reviewer

   Default agents (read-only)
   General
   Explore
   Plan

 ↑↓ navigate · Enter to select · Esc to close

 Agents live in .commandcode/agents/ (project) and
 ~/.commandcode/agents/ (all projects) - edit the files directly anytime.
 Docs: https://commandcode.ai/docs/core-concepts/custom-agents

Sections only appear when they have agents. With no custom agents, the title reads Agents (No custom agents).

The manual wizard

Pick Create manually to fill in every field yourself. The steps are: location → identifier → system prompt → description → tools → model → confirm.

Choose where it lives:

 Create new agent
 Choose location

 > 1. Project (.commandcode/agents/)
   2. Personal (~/.commandcode/agents/)

Project agents are committed with the repo and shared with your team. Personal agents live in your home directory and work in every project.

Name it, prompt it, describe when to use it. Three steps set the identifier (must be unique, not a reserved name), the system prompt, and the description Command Code matches against to decide when to delegate.

 Create new agent
 Agent type (identifier)

 Enter a unique identifier for your agent:

 > code-reviewer_
   e.g. code-reviewer, unit-tester

 Enter to continue · Esc to cancel

Select tools. Categories toggle groups; Show advanced options lists individual tools. The first row saves your choice.

 Create new agent
 Select tools

 > [ Continue ]
   ────────────────────────────────
   [x] Read-only tools
   [x] Edit tools
   [ ] Execution tools
   [x] Search tools
   [ Show advanced options ]

 3 tools selected

Select model. Keep the session model, or pin one this agent always uses.

 Create new agent
 Select model

 > 1. Inherit from session (default)
   2. Pick a specific model

Confirm. A summary shows every field before the file is written:

 Create new agent
 Confirm and save

 Name:        code-reviewer
 Location:    .commandcode/agents/ (project)
 Tools:       Read-only, Edit, Search
 Model:       Inherit from session

 Description (Tells Command Code when to use this agent):
   Use this agent when you are done writing code and want a
   diff reviewed for bugs and security issues.

 System Prompt:
   You are a meticulous code reviewer. Prioritize correctness,
   security, and clear feedback. Cite file paths and lines.

 Press Enter to save · Esc to cancel

Agents you add or edit are picked up on the next turn - no restart.

Edit the file directly

An agent is a Markdown file. The front matter configures it; the body is the system prompt.

---
name: code-reviewer
description: Use after writing code to review a diff for bugs and security issues.
tools: read_file, read_multiple_files, grep, glob
model: claude-sonnet-5
---

You are a meticulous code reviewer. Prioritize correctness, security, and clear
feedback. Cite file paths and line numbers. Be concise.

Drop the file in .commandcode/agents/ (project) or ~/.commandcode/agents/ (personal) and it loads on the next turn. Full field list is in the Reference.

How it works

You don't call a subagent yourself. You describe what you want, and Command Code decides when to delegate by calling its built-in agent tool. The subagent runs in its own loop, does the work, and returns one result.

Parallel runs. Command Code starts independent subagents at the same time by making several agent calls in one turn. Five explorers, or three agents each editing a different module, run together instead of in sequence.
Isolated context. A subagent's file reads and reasoning stay in its own context window, so a long exploration doesn't fill up the main conversation.
Own model. An agent can pin its own model, so a slow planner and a fast implementer keep separate prompt caches.
One level deep. Subagents can't start their own subagents - the agent tool is removed from their tool set.

Background runs

A run can be detached. When it's started in the background (or the agent sets background: true), the agent tool returns right away with an agent_id and the main session keeps going. The result is collected later with the agent_output tool, which can wait for it, check status, or kill the run.

Where agents load from

Source	Path	Notes
Bundled	(built-in)	General, Explore, Plan - always present, read-only
Personal	`~/.commandcode/agents/`	Every project on your machine
Project	`.commandcode/agents/`	Committed with the repo; shared with the team

They load in that order and the first definition of a name wins. Files are re-scanned each turn, so adds, edits, and deletes take effect right away.

Note

Reserved names (explore, plan, review, general) are used by built-in behavior. A custom file with one of these names is ignored.

Reference

Frontmatter fields

Only these keys are read; anything else is ignored. All except name are optional.

Name
name
Type
string
Required
Required
Description
The agent's id, the name Command Code delegates to. Defaults to the filename without .md (code-reviewer.md → code-reviewer). Characters outside a-z A-Z 0-9 _ - become _. Can't be a reserved name.
Name
description
Type
string
Description
When to use the agent. This is the text Command Code matches against, so be specific. Defaults to empty.
Name
tools
Type
string | string[]
Description
Tools the agent may use. "*" grants all; otherwise a comma- or space-separated list (or a YAML array). Omit it and the agent gets no tools.
Name
disallowedTools
Type
string | string[]
Description
Deny list applied after tools. Deny beats allow, so pair it with tools: "*" to mean "everything except these". Same format as tools.
Name
model
Type
string
Description
Model this agent always runs on: any /model id. See Available models for the full list, or run cmd --list-models. Omit it (or set model: inherit) to follow the session model.
Name
maxTurns
Type
integer
Description
Caps the agent's loop. Default 100.
Name
permissionMode
Type
string
Description
Overrides the session's permission mode for this agent. One of default, auto-accept, bypass, plan, dont-ask. A session already in plan or bypass wins. Defaults to inheriting the session.
Name
background
Type
boolean
Description
When true, every run detaches: the agent tool returns an agent_id and results come from agent_output.
Name
showOutput
Type
boolean
Description
When true, the agent's final message is shown verbatim in the feed instead of a short "done" line. The model still receives it as the result.

Tools

Tool ids are the same names shown in the /agents wizard's advanced list. How tools is read:

tools: "*" - every tool, including connected MCP tools.
tools: read_file, grep, glob - an allowlist. Comma- or space-separated; a YAML array also works.
Omitted - no tools.

Common ids by category:

Category	Tool ids
Read-only	`read_file`, `read_directory`, `read_multiple_files`, `grep`
Edit	`edit_file`, `write_file`
Execution	`shell_command`, `run_command`, `kill_shell`
Search	`web_search`, `web_fetch`
Other	`glob`, `todo_write`, `task_create`, `task_update`, `task_list`, `task_get`, `task_output`, `task_stop`, `cron_create`, `cron_list`, `cron_delete`, `get_diagnostics`, `get_command_code_knowledge`, `taste`, `ask_user_question`, `sleep`, `config`, `enter_plan_mode`, `exit_plan_mode`, `enter_worktree`, `exit_worktree`

MCP tools go in by their raw name, e.g. mcp__github__get_me. The agent and agent_output tools can't be granted - that's what keeps delegation one level deep.

Models

The model field takes any id you'd pass to /model. To find one:

See Available models for the full list,
open the /model picker, or
run cmd --list-models in the shell.

Use ids exactly as --list-models prints them. Examples: claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5, moonshotai/kimi-k2.6, zai-org/glm-5.2.

Omitting model is the same as model: inherit - the agent follows the session's /model. Pinning a model gives the agent its own prompt cache, so a slow planner and a fast implementer don't thrash each other's.

Full example

Every field, with valid values. Copy it and delete what you don't need.

.commandcode/agents/report-writer.md

---
name: report-writer
description: "Writes a structured research report from the current repo. Delegate long-form summarization and analysis tasks here."
tools: "*"                                  # grant everything…
disallowedTools: shell_command, write_file  # …except shells and file writes
model: claude-opus-4-8                       # any /model id, or omit to inherit
maxTurns: 40                                 # cap the loop (default 100)
permissionMode: plan                         # default|auto-accept|bypass|plan|dont-ask
background: true                             # detach; collect via agent_output
showOutput: true                             # render the final report in the feed
---

You are a research report writer. You receive one self-contained task and
produce a complete, well-structured Markdown report as your final message.

- Gather only the files and facts the task requires.
- Work on your own - you can't ask follow-up questions.
- Your final message is the deliverable; make it complete.

Quick lookup:

Field	Type	Values	Default
`name`	string	id, sanitized to `a-z A-Z 0-9 _ -`; not reserved	filename
`description`	string	any text	`""`
`tools`	string \| list	`"*"`, or comma/space-separated ids, or a YAML list	none
`disallowedTools`	string \| list	same format as `tools`; applied after it	-
`model`	string	any `/model` id, or `inherit`	inherit
`maxTurns`	integer	positive integer	`100`
`permissionMode`	string	`default`, `auto-accept`, `bypass`, `plan`, `dont-ask`	inherit
`background`	boolean	`true` / `false`	`false`
`showOutput`	boolean	`true` / `false`	`false`

Next steps

Interactive mode - slash commands and session controls
Background tasks - detached, long-running work
Memory - project and user instructions in AGENTS.md
Skills - reusable skill packages vs. full subagents