Subagent

A Subagent is a specialized agent in Qoder CLI for handling a specific class of work. It can have its own system prompt, tool set, model configuration, permission mode, runtime limits, and hooks. Use Subagents to delegate focused work such as code exploration, implementation planning, API review, test authoring, and migration assessment.

Quick Start

1. Run /agents in TUI to open the configuration panel.
2. Press Tab to switch to the User or Project tab.
3. Select Create new agent..., enter a Subagent description, and confirm.
4. After generation, invoke it directly in the conversation:

Use the api-reviewer subagent to review this API design

What a Subagent Is

Use a Subagent when a task spans many files, needs stable domain-specific criteria, or would otherwise fill the main conversation with search and analysis details. The main session understands the user goal and coordinates the work; the Subagent completes a clear subtask and returns its result to the main session.

Core benefits:

Benefit	Description
Keep the main session focused	Each Subagent has its own conversation context, system prompt, tool registry, transcript, and compression flow. Its intermediate search and reasoning do not directly enter the main conversation.
Improve specialized task quality	Configure task-specific prompts, tool allowlists, tool denylists, MCP servers, models, permissions, and runtime limits so review, exploration, and planning tasks follow stable criteria.
Reuse team workflows	User-level and project-level Subagents can be reused repeatedly and shared with a project, giving teams a consistent workflow for recurring tasks.
Control tool and permission boundaries	Each Subagent can have its own tool set and permission mode, reducing the chance that a high-risk task uses the wrong capability.
Orchestrate complex work	Qoder CLI can dispatch independent Subagents in parallel. When background Subagent sessions are enabled, independent work can also run in the background and notify the main session later.

Core capabilities:

Capability	Description
Isolated context	Each Subagent has its own conversation context, system prompt, tool registry, transcript, and compression flow. Its intermediate search and reasoning do not directly enter the main conversation.
Custom capability set	Configure task-specific prompts, tool allowlists, tool denylists, MCP servers, models, permissions, and runtime limits.
Concurrent execution	Qoder CLI can dispatch multiple independent Subagents in parallel.
Background execution	When background Subagent sessions are enabled, independent work can run in the background and notify the main session later.
Workspace isolation	Use worktree isolation when a Subagent should run in a separate git worktree.

If you already know the exact file or command, use the direct tool. Subagents are best for open-ended, multi-step work that needs judgment and synthesis.

Built-In Subagents

Qoder CLI registers a set of built-in Subagents. The exact list in the BuiltIn tab of /agents can vary by version, runtime mode, and enabled features.

Common built-in Subagents:

Name	Capability
general-purpose	General research Subagent for complex search, multi-file analysis, call-path tracing, and multi-step work. When a dispatch omits the Subagent type, the agent tool defaults to this Subagent.
Explore	Fast read-only code exploration for finding files, searching symbols, and understanding existing implementations. It inherits available tools, removes write and control tools, and uses exploration-oriented model settings.
Plan	Read-only implementation planning for outlining the approach, critical files, sequencing, and architectural trade-offs before editing.

Depending on mode and feature flags, you may also see:

Name	When It Appears	Capability
qoder-guide	Non-SDK mode	Answers Qoder CLI usage, configuration, Skills, Agents, MCP, and Hooks questions.
statusline-setup	TUI mode	Configures a custom status line. It may read shell configuration, create scripts, and update settings.

Built-in Subagents are provided and maintained by Qoder CLI. They are not edited like user-level or project-level Subagents. To customize behavior, create a custom Subagent with a new name or the same name and rely on source priority.

View and Use Subagents

View Available Subagents

TUI

In TUI, enter:

/agents

The /agents panel groups Subagents by source and lets you inspect details, create Subagents, enable or disable them, edit custom entries, and reload definitions. After changing .qoder/agents/ or ~/.qoder/agents/, run:

/agents reload

Non-Interactive

In non-interactive environments, use:

qodercli agents list

The list includes all discovered Subagents. When a Subagent is shadowed by a higher-priority source with the same name, the listing marks it as shadowed.

Sources and Priority

Qoder CLI discovers Subagents from multiple sources. Same-name definitions override each other by priority, from low to high:

Priority	Source	Entry	Description
1	Built-in	BuiltIn tab in /agents	Capabilities shipped with Qoder CLI. They are provided and maintained by Qoder CLI and are usually not edited directly.
2	User	~/.qoder/agents/*.md	User-level Subagents. They apply across this user’s projects.
3	Project	.qoder/agents/*.md	Project-level Subagents. They apply to the current project, are suitable for project sharing, and depend on folder trust.
4	Plugin	Installed plugins	Subagents provided by plugins. The Plugin tab appears only when plugin Subagents exist, and they are usually maintained by the plugin.
5	Flag	--agents JSON	Temporary Subagents injected into the current process. They have the highest priority and only apply to this command or session.

The highest-priority same-name definition is active; overridden definitions are marked as shadowed in qodercli agents list.

Explicit Invocation

TUI Mode

In a TUI conversation, the most stable way to invoke a Subagent is to name it directly in the input:

Use the api-reviewer subagent to review this API design

You can also mention a loaded Subagent with @ in TUI input:

@api-reviewer review this API design and return only required changes

Headless Mode

In Headless mode, pass the same natural-language request through qodercli -p:

qodercli -p "Use the api-reviewer subagent to review this API design"

Implicit Invocation

TUI Mode

In a TUI conversation, you can describe the task and let Qoder CLI match it against each Subagent’s description:

Review this API design

Headless Mode

In Headless mode, pass only the task description through qodercli -p:

qodercli -p "Review this API design"

If a specific Subagent must be used, name it explicitly; in TUI, you can also use @name.

Use a Subagent as the Session Agent

--agent uses an already loaded Subagent as the main agent for the current session. In this mode, that definition’s initialPrompt is used as the session’s initial prompt.

TUI Mode

Specify --agent when starting TUI:

qodercli --agent api-reviewer

After TUI starts, the current session uses api-reviewer as the main agent. Running an agent from the /agents panel does not switch the main session agent; it submits an @agent-name request for a single Subagent invocation.

Headless Mode

In Headless mode, use it together with -p:

qodercli --agent api-reviewer -p "Review this API design"

Orchestrate Multiple Subagents

Describe the Subagent execution order in natural language, and Qoder CLI will process the task according to that sequence.

TUI Mode

Enter the orchestration request directly in a TUI conversation:

First use the general-purpose subagent to check the implementation approach, then use the api-reviewer subagent to review the API design

Headless Mode

In Headless mode, pass the same orchestration request through qodercli -p:

qodercli -p "First use the general-purpose subagent to check the implementation approach, then use the api-reviewer subagent to review the API design" --max-turns 10

For independent tasks, explicitly ask for parallel dispatch. For dependent work, describe the order as shown above. --max-turns limits the whole Headless query. To limit a single Subagent invocation, set maxTurns in that Subagent’s configuration.

Customize Subagents

Create Persistent Local Subagent Definitions

Method 1: AI-Assisted Generation (Recommended)

This is the easiest way to create a Subagent. Describe what you need in natural language, and Qoder CLI generates a complete configuration file for you.

Steps:

1. Run /agents in TUI to open the configuration panel.
2. Press Tab to switch to the User or Project tab.
3. Select Create new agent... and press Enter.
4. Enter a Subagent description and press Enter to confirm.

> /agents
------------------------------------------------------------------------------------------
Agents:  User  [Project]  BuiltIn

-> Create new agent...

Agent list:
No project agents found.

Press Enter to select - Esc to exit - Tab to cycle tabs - Up/Down to navigate

After you enter a description, Qoder CLI generates the configuration:

> /agents
------------------------------------------------------------------------------------------
Agents:  User  [Project]  BuiltIn

Describe the agent:

> Help me review RESTful api design

Press Enter to select - Esc to exit - Tab to cycle tabs - Up/Down to navigate

When generation finishes, you can find and refine the configuration file in the selected directory:

# Project-level (Project tab)
.qoder/agents/

# User-level (User tab)
~/.qoder/agents/

Tip: start with AI-assisted generation, then iterate until the Subagent matches your specific workflow. This gives you a strong customizable baseline.

Method 2: Write Configuration Manually (Advanced)

If you need full control over Subagent configuration, create a Markdown configuration file manually:

# Project-level, only active in the current project, suitable for version control
.qoder/agents/api-reviewer.md

# User-level, active across this user's projects
~/.qoder/agents/api-reviewer.md

Markdown files must start with YAML frontmatter. Frontmatter declares configuration; the Markdown body is the local Subagent’s system prompt.

---
name: api-reviewer
description: Review API designs, endpoint naming, request methods, status codes, error responses, and versioning.
tools: [Read, Grep, Glob]
disallowedTools: [Write, Edit]
permissionMode: default
model: inherit
maxTurns: 8
timeoutMins: 10
color: cyan
---

You are an API design reviewer.

Focus on:
- Resource naming and URL structure
- Request method semantics
- Status code and error response consistency
- Pagination, filtering, and versioning

Return concise findings grouped by severity. Include concrete examples when possible.

To run a Subagent in a separate worktree, add this to its frontmatter:

isolation: worktree

The filename does not define the Subagent name. The actual name comes from the frontmatter name field.

Inject Temporary Subagents with --agents

--agents is useful for Headless runs, scripts, and one-off automation. It accepts a JSON object whose keys are Subagent names and whose values are definitions. Subagents injected with --agents only exist for the current process and have the highest priority for name conflicts.

qodercli \
  --agents '{"api-reviewer":{"description":"Review API designs","prompt":"You are an API reviewer.","tools":["Read","Grep","Glob"],"maxTurns":6}}' \
  -p "Use the api-reviewer subagent to review docs/api.yaml"

--agents uses the prompt field as the system prompt. The current JSON schema supports description, prompt, tools, disallowedTools, mcpServers, model, effort, color, maxTurns, initialPrompt, skills, and permissionMode. Use Markdown configuration when you need timeoutMins, temperature, hooks, memory, background, or isolation.

Configure Subagents

Select a Scope

When creating or injecting a custom Subagent, choose one of these scopes:

Scope	Configuration Entry
Project	.qoder/agents/*.md
User	~/.qoder/agents/*.md
Flag	--agents

Configure Tools

tools and disallowedTools can be comma-separated strings or string arrays. String arrays can use either YAML inline-array syntax or YAML block-list syntax:

tools: Read,Grep,Glob

tools: [Read, Grep, Glob]

tools:
  - Read
  - Grep
  - Glob

Common tool names include Read, Grep, Glob, Bash, Write, Edit, WebFetch, WebSearch, and Agent.

MCP tools use fully qualified names:

tools:
  - mcp__docs__search
  - mcp__docs__*
  - mcp__*

To allow a Subagent to call only specific other Subagents, use the Agent(name) expression:

tools:
  - Read
  - Grep
  - Agent(Explore, Plan)

To prevent further Subagent dispatch entirely, disable Agent:

disallowedTools: [Agent]

Tool handling order is: register allowed tools from tools, then remove tools listed in disallowedTools. MCP tools must be discovered through mcpServers or global MCP configuration and also allowed by tools before the Subagent can use them.

Configure MCP

Reference an already configured MCP server:

mcpServers:
  - docs

Or define an MCP server inline for this Subagent:

mcpServers:
  docs:
    command: ./scripts/docs-mcp
    args: ["--stdio"]
    include_tools: ["search", "read"]

mcpServers supports both array and object formats. Inline server fields:

Field	Meaning
command	Command that starts a stdio MCP server.
args	Command argument array.
env	Environment variables passed to the MCP server.
cwd	MCP server working directory.
url / http_url	Remote MCP server URL.
headers	Remote request headers.
tcp	TCP connection address.
type	Transport type, sse or http.
timeout	Connection or call timeout.
trust	Whether to trust this MCP server.
description	Server description.
include_tools	Include only specific MCP tools.
exclude_tools	Exclude specific MCP tools.

Define Hooks

hooks in Subagent frontmatter are scoped to that Subagent session. Supported events include PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, and Notification.

hooks does not support string shorthand. The value of each event must be a matcher array, and each matcher declares one or more hooks through its own hooks array.

Inside a Subagent, Stop is remapped to SubagentStop, so it fires when that Subagent finishes rather than when the main session ends.

hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: ./scripts/check-subagent-command.sh
          timeout: 30
          statusMessage: Checking command
  Stop:
    - hooks:
        - type: command
          command: ./scripts/subagent-finished.sh

Each event contains matchers; each matcher has a hooks array with these hook types:

type	Required Field	Description
command	command	Run a local command. Optional shell, timeout, if, and statusMessage.
http	url	Call an HTTP endpoint. Optional headers, allowedEnvVars, timeout, if, and statusMessage.
prompt	prompt	Run a model check from a prompt. Optional model, timeout, if, and statusMessage.
agent	prompt	Run an independent hook agent. Optional model, timeout, if, and statusMessage.

The frontmatter schema accepts once, but ordinary Subagent frontmatter does not preserve one-shot hook semantics. If you need one-shot behavior, implement it in the hook command or external state.

Configure Permission Modes

permissionMode controls approval behavior for Subagent tool calls.

Value	Meaning
default	Use the default permission policy and ask when needed.
acceptEdits	Automatically accept edit operations.
bypassPermissions	Skip permission prompts. If security policy disables it, it is demoted to acceptEdits.
dontAsk	Do not proactively ask; operations that require asking are denied.
auto	Use automatic policy classification.
plan	Enter this Subagent’s own planning state, useful for read-only planning.

Use the canonical values above in public configuration. Runtime parsing also tolerates case and separator variants; yolo is parsed as bypassPermissions for compatibility, but bypassPermissions is the recommended spelling.

Notes:

• If permissionMode is omitted, the Subagent inherits the current parent session mode.
• If the parent session is already in acceptEdits, bypassPermissions, or auto, the Subagent cannot make itself stricter through its own configuration.
• plan does not affect the main session’s plan state. It only applies inside the Subagent’s isolated context.

Configure Remote Subagents

Remote Subagents are loaded from Agent Cards. They do not use the Markdown body as a system prompt; behavior comes from the remote Agent Card’s exposed capabilities and description.

---
kind: remote
name: docs-helper
description: Answer questions using the remote documentation agent.
agentCardUrl: https://agent.example/.well-known/agent-card.json
---

You can also use agentCardJson to inline the Agent Card JSON. Remote Subagents support the auth field; common auth types include apiKey, http, and oauth. If authentication is required, prefer user-level configuration so credentials are not committed to the project repository.

Override Existing Subagents with settings.json

settings.json cannot create new Subagents. It only overrides Subagents that have already been discovered. Current overrides support enabled state, model configuration, runtime limits, tool allowlists, and appended MCP servers.

{
  "agents": {
    "overrides": {
      "api-reviewer": {
        "enabled": true,
        "tools": ["Read", "Grep", "Glob"],
        "runConfig": {
          "maxTurns": 6,
          "maxTimeMinutes": 10
        },
        "modelConfig": {
          "model": "auto",
          "generateContentConfig": {
            "temperature": 0.2
          }
        },
        "mcpServers": {
          "docs": {
            "command": "./scripts/docs-mcp",
            "args": ["--stdio"]
          }
        }
      }
    }
  }
}

Common uses:

• Set "enabled": false to hide a Subagent temporarily.
• Give one Subagent a different model and temperature.
• Limit maximum turns or maximum runtime for automation.
• Tighten the tool set without editing the original Markdown.
• Append MCP servers to an existing local Subagent.

Plugin-provided Subagents apply an additional safety policy: hooks, mcpServers, and permissionMode are removed, and isolation is preserved only when it is worktree.

Local Subagent Full Field Reference

The fields below apply to Markdown frontmatter. Unknown fields are ignored.

Field	Required	Values	Meaning
name	Yes	Non-empty string	Subagent name. Prefer clear, stable names that are easy to mention in natural language.
description	Yes	Non-empty string	Description of when to use this Subagent. Qoder CLI uses it for selection.
background	No	Boolean	Whether the Subagent should launch in the background by default. Requires background Subagent sessions to be enabled.
color	No	red, blue, green, yellow, purple, orange, pink, cyan	Color shown while the Subagent is running in TUI.
disallowedTools	No	String or string array	Tool denylist, applied after tools are registered.
effort	No	low, medium, high, xhigh, max, or positive integer	Reasoning effort or budget.
hooks	No	Hook configuration object	Frontmatter hooks scoped only to this Subagent session.
initialPrompt	No	String	Initial prompt when this definition is used through --agent as the session agent. Normal Subagent calls do not inject it as the task prompt.
isolation	No	Prefer worktree	Isolation mode. worktree runs the Subagent in a separate git worktree. Omitted means the default workspace.
kind	No	local	Type. Omitted definitions are treated as local Subagents. Remote Subagents use remote; see below.
maxTurns	No	Positive integer	Maximum conversation turns for one Subagent invocation.
mcpServers	No	Server-name array, inline server object, or a mix	Extra MCP discovery for this Subagent. Actual use is still controlled by tools and disallowedTools.
memory	No	user, project, local	Persistent memory scope for this Subagent. Only active when global automatic memory is enabled.
model	No	Any model name or model alias; common values include inherit, auto, lite, efficient, performance	Model used by this Subagent. Omitted means inherit, using the current session model.
permissionMode	No	default, acceptEdits, bypassPermissions, dontAsk, auto, plan	Permission mode for this Subagent. Omitted means inherit the current parent session mode.
skills	No	String or string array	Restrict which Skills this Subagent can use.
temperature	No	Number	Model temperature. When omitted, the loader writes a default temperature configuration.
timeoutMins	No	Positive integer	Maximum runtime for one Subagent invocation, in minutes.
tools	No	String or string array; supports *	Tool allowlist. Omitted means use the current available tool set; * means all tools.

Test the Result

After creating or editing a Subagent, verify it in this order:

1. Run /agents reload or start a new session.
2. Confirm it appears under the expected source in /agents or qodercli agents list.
3. Check that description clearly explains when it should be used.
4. Invoke it by explicit name once:

Use the api-reviewer subagent to review this API:

POST /login
GET /logout

5. If it is configured as read-only, ask it not to modify files and confirm no write operation appears.
6. If it has disallowedTools, ask for a blocked capability and confirm it chooses another path or explains the restriction.
7. If it uses MCP, confirm the target MCP tool is discovered and not blocked by tools.
8. If it uses background or background execution, confirm the main session does not wait for the full result and that completion arrives as a later notification.

If it is not invoked, first use the explicit name or @name. If it is still unavailable, check load errors in the /agents panel.

Best Practices

• Give each Subagent one clear responsibility instead of mixing review, implementation, testing, and release work.
• Write description for selection, and write the body prompt for the Subagent itself. Both should be specific.
• Start with read-only tools, then add Edit, Write, or Bash only when needed.
• For higher-risk Subagents, set maxTurns, timeoutMins, and an explicit permissionMode.
• Use isolation: worktree when a Subagent needs an isolated working copy, then inspect the returned worktree path and actual diff.
• If the Subagent depends on MCP tools, configure both mcpServers and tools so the tools are discovered and allowed.
• Use project-level Subagents for team-shared standards and user-level Subagents for personal preferences or cross-project workflows.
• Test with explicit invocation before relying on implicit selection.
• For plugin-shipped Subagents, do not depend on hooks, mcpServers, or permissionMode, because the plugin safety policy removes those fields.

FAQ

How is a Subagent different from the main session?

A Subagent runs in an independent context with its own system prompt, tool set, runtime limits, and permission declaration. Its result is returned to the main session, which can summarize or continue the work.

Why does my project-level Subagent not appear?

Confirm the file is at .qoder/agents/<name>.md, the frontmatter includes at least name and description, and the current project is trusted. Then run /agents reload and check load errors in the /agents panel.

Why did a same-name Subagent not take effect?

Higher-priority sources override lower-priority sources. The order is Built-in < User < Project < Plugin < Flag. Use qodercli agents list to see shadowed entries.

What is the difference between description and the body prompt?

description explains when to call the Subagent and affects selection. The body prompt is the system prompt the Subagent sees after it is invoked and affects how it performs the task.

Can multiple Subagents run at the same time?

Yes. Qoder CLI can dispatch independent Subagents concurrently. For dependent work, describe the order in your prompt.

Can a Subagent call another Subagent?

Yes, if the Agent tool remains available. Use Agent(name) or Agent(name1, name2) to allow only specific Subagents. Use disallowedTools: [Agent] to prevent further dispatch.

Why can my Subagent not use the MCP tool I configured?

First confirm the MCP server is discovered through mcpServers or global MCP configuration. Then confirm tools allows the fully qualified MCP tool name. mcpServers discovers tools; it does not automatically authorize every MCP tool.

Why did the Subagent permission mode not become stricter?

If the parent session is already in acceptEdits, bypassPermissions, or auto, the Subagent cannot make itself stricter through permissionMode. If permissionMode is omitted, it inherits the current parent session mode.

Where do background Subagent results appear?

When running in the background, the main session first receives a launch result. The task result arrives later as a completion notification. Do not summarize expected results before the notification arrives.

Can I edit built-in or plugin Subagents?

Built-in and plugin Subagents are not meant to be edited directly. Create a user-level or project-level Subagent instead. If you use the same name to override behavior, pay attention to source priority and plugin safety policy.