Custom Agents | Command Code - Command Code Docs
Command Code

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.

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

Creating an agent

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, 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

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

FieldTypeRequiredDefaultDescription
namestringYesfilenameAgent id Command Code delegates to. Sanitized to a-z A-Z 0-9 _ -; can't be a reserved name.
descriptionstringNo""When to use the agent, the text Command Code matches against. Be specific.
toolsstring | string[]NononeTools the agent may use. "*" grants all; otherwise a comma/space-separated list or YAML array.
disallowedToolsstring | string[]No-Deny list applied after tools (deny beats allow). Same format as tools.
modelstringNoinheritAny /model id. Omit or set inherit to follow the session model.
reasoningEffortstringNomodel defaultReasoning level the pinned model supports; an unsupported level falls back to the model default.
maxTurnsintegerNo100Caps the agent's loop.
permissionModestringNoinheritOverrides the session mode: default, auto-accept, bypass, plan, dont-ask. A session already in plan/bypass wins.
backgroundbooleanNofalsetrue detaches every run: the agent tool returns an agent_id; results come from agent_output.
showOutputbooleanNofalsetrue shows the agent's final message verbatim in the feed instead of a short "done" line.

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:

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.

Reasoning effort

reasoningEffort pins how hard the agent thinks, independent of the session's /effort. Pin/select a reasoning level the agent's model supports. To see a model's exact set, open the /model picker and select the model - its reasoning-effort step lists precisely the levels that model accepts.

The value is validated in two stages so a bad one never reaches the provider mid-delegation:

  • At load time an unknown level (a typo like meduim) is dropped with a warning, and the agent falls back to the model default - the file still loads.
  • At runtime, the level is checked against the model actually chosen (an inherit model isn't known until launch).
  • A level the resolved model doesn't support falls back to the model default rather than being clamped to a different level.

Omit it to run at the model's default effort.

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 reasoningEffort: high # a level THIS model supports (varies by model); omit for default 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.

Next steps