Custom Agents

Custom agents are specialized subagents Command Code can delegate to. Each one gets its own context window, system prompt, and tool set, so you can keep exploration, planning, or niche workflows separate from the main session.

Built-in defaults (Explore and Plan) are always available. Your definitions live alongside them as Markdown files in project .commandcode/agents/ or personal ~/.commandcode/agents/.

Open the agents manager

In interactive mode, run:

/agents

This opens the agents screen: your custom agents (if any), Create new agent, and the default agents list.

Command Code agents screen listing Create new agent and default agents Explore and Plan

The /agents screen: create custom agents or use built-in Explore and Plan.

Create a new agent

Choose Create new agent, then walk through the wizard.

1. Choose where it lives

Scope	Path	When to use
Project	`.commandcode/agents/` in the current repo	Shared with the team; commit in Git.
Personal	`~/.commandcode/agents/`	Available in every project on your machine.

Create new agent: choose Project or Personal location

Pick project-level or personal storage for the new agent.

2. Choose how to build it

Option	Description
Generate with Command Code (recommended)	Describe the agent’s role and when to use it; Command Code drafts configuration for you.
Manual configuration	Set the identifier, system prompt, “when to use” description, and tools yourself.

Create new agent: Generate with Command Code or Manual configuration

Generate from a description, or configure every field manually.

3. Generate: write a thorough description

If you chose Generate with Command Code, you’ll see a prompt like the one below. The more specific you are about responsibilities, boundaries, and when delegation should happen, the better the result.

Create new agent: text field to describe what the agent should do

Describe what the agent should do and when Command Code should delegate to it.

Command Code will automatically generate:

Agent name
Description (when to use it)
System prompt

You only need to review them and then choose which tools the agent should have access to.

Create new agent: tool selection screen with categories like read-only, edit, execution, and search tools

Select tools for the agent, then continue to save.

After generation, you’ll confirm tools and save. Manual creation follows the same tool-selection and confirmation steps, but you’ll enter the name, description, and system prompt yourself.

Agent files (manual editing)

Each agent is a Markdown file with YAML front matter and a body that becomes the system prompt.

name — Identifier and filename (e.g. security-review.md → agent security-review).
description — Tells Command Code when to use this agent.
tools — Comma-separated tool list, "*" for all tools, or a restriction such as read-only style lists.

Note

Do not use reserved names for custom agents: explore, plan, review, and general. Those names are reserved for built-in or internal behavior; custom files with those names are ignored.

Example shape:

Example agent file

---
name: "security-review"
description: "Use for dependency and secret-scanning review before release."
tools: "glob, grep, read_file, think"
---

You are a security-focused reviewer. Prioritize dependency risks, secrets in code,
and unsafe patterns. Be concise; cite file paths and lines.

You can edit files directly in .commandcode/agents/ or ~/.commandcode/agents/, or recreate them through /agents.

Next steps

Interactive mode — slash commands and session controls
Memory — project and user instructions in AGENTS.md
Skills — reusable skill packages vs. full subagents

Core Concepts