Subagent - Qoder CN

Subagents are AI agents in Qoder CN CLI that specialize in specific types of tasks. Each subagent can have its own system prompt, tool set, model configuration, permission mode, run limits, and hooks—ideal for delegating focused work like code exploration, design, API review, test completion, or migration assessment to a more specialized executor.

Quick Start

Run /agents in TUI to open the configuration panel.
Press Tab to switch to the User or Project tab.
Select Create new agent..., enter a subagent description, and confirm.
Once generated, invoke it directly in the conversation:
```
Use the api-reviewer subagent to review this API design
```

What is a Subagent

When a task requires exploring across many files, needs stable domain-specific judgment, or you don't want the search process to fill the main conversation context, use a Subagent. The main conversation understands the user's goal and orchestrates; the Subagent completes a clear sub-task and returns the final result. Core value of Subagents:

Value	Description
Keep the main conversation focused	Each Subagent has its own conversation context, system prompt, tool registry, run log, and compression flow. Its intermediate reading, searching, and thinking do not directly enter the main conversation
Improve quality of specialized tasks	You can configure dedicated prompts, tool allowlists, disallowed tools, MCP services, models, permissions, and run limits per task, so review, exploration, and planning tasks follow stable standards
Reuse team workflows	User-level and project-level Subagents can be reused and shared with a project, letting teams use consistent processes for the same tasks
Control tool and permission boundaries	Each Subagent can have its own tool set and permission mode, reducing the risk of misusing high-risk tools
Support complex task orchestration	Independent tasks can run concurrently. When background Subagent sessions are enabled, independent tasks can run in the background and notify the main conversation on completion

Core features of Subagents:

Feature	Description
Context isolation	Each Subagent has an independent conversation context, system prompt, tool registry, run log, and compression flow. Its intermediate work does not directly enter the main conversation
Capability customization	You can configure prompts, tool allowlists, disallowed tools, MCP services, model, permissions, and run limits per task
Concurrent execution	For mutually independent tasks, Qoder CN CLI can dispatch multiple Subagents in parallel
Background execution	When background Subagent sessions are enabled, independent tasks can run in the background and notify the main conversation on completion
Isolated workspace	For independent changes, use `worktree` isolation so the Subagent runs in a separate git worktree

If you already know the exact file or command, use the corresponding tool directly—it is usually more efficient. Subagents are better suited to open-ended, multi-step tasks that require judgment and synthesis.

Built-in Subagents

Qoder CN CLI registers a set of built-in Subagents. The BuiltIn tab in /agents may show different lists depending on version, run mode, and feature toggles—rely on the actual displayed list. Common built-in Subagents:

Name	Capability
`general-purpose`	General-purpose research Subagent. Suitable for complex searches, multi-file analysis, call-chain tracing, and multi-step tasks. Used by default when no Subagent type is explicitly specified
`Explore`	Fast read-only code exploration. Ideal for finding files, searching symbols, and understanding existing implementations. Inherits available tools, then removes write and control tools, and uses an exploration-oriented model configuration
`Plan`	Read-only design planning. Suitable for outlining implementation paths, key files, dependency order, and architectural trade-offs before changing code

In specific modes or when certain features are enabled, you may also see:

Name	When shown	Capability
`qoder-guide`	Non-SDK mode	Answers questions about Qoder CN CLI usage, configuration, Skills, Agents, MCP, Hooks, etc.
`statusline-setup`	TUI mode	Configures a custom status line; may read shell configuration, create scripts, and update settings
`SaveMemory`	When memory management is enabled	Manages cross-session memory, preferences, and facts

Built-in Subagents are provided and maintained by Qoder CN CLI and cannot be edited like user-level or project-level Subagents. To customize behavior, create a custom Subagent with the same or different name and override it via source priority or explicit invocation.

Viewing and Using Subagents

View available list

TUI: In TUI, run:

/agents

The /agents panel groups Subagents by source and supports viewing details, creating, enabling/disabling, editing custom items, and reloading. After modifying .qoder/agents/ or ~/.qoder-cn/agents/, run:

/agents reload

Headless: In non-interactive environments, use:

qoderclicn agents list

The list shows all discovered Subagents. Same-name Subagents overridden by higher-priority sources are marked as shadowed.

Sources and priority

Qoder CN CLI discovers Subagents from multiple sources. Same-name definitions are overridden by priority, from lowest to highest:

Priority	Source	Location	Description
1	Built-in	`BuiltIn tab of /agents`	Built-in capabilities provided and maintained by Qoder CN CLI. Usually not edited directly
2	User	`~/.qoder-cn/agents/*.md`	User-level Subagent, effective across multiple projects for the current user
3	Project	`.qoder/agents/*.md`	Project-level Subagent, effective for the current project. Suitable for sharing with the project. Subject to folder trust status
4	Plugin	Provided by installed plugins	Subagents provided by plugins. The Plugin tab shows only when plugin Subagents exist. Usually maintained by the plugin
5	Flag	`--agents` JSON	Subagents injected into the current process temporarily. Highest priority; effective only for the current command or session

The effective definition is the highest-priority same-name definition. Overridden definitions are marked shadowed in qoderclicn agents list.

Explicit invocation

TUI mode: In a TUI session, the most stable way is to write the Subagent name directly:

Use the api-reviewer subagent to review this interface design

You can also use @ in TUI input to mention an already loaded Subagent:

@api-reviewer Review this interface design, return only the points that need changes

Headless mode: Pass the same natural-language request via qoderclicn -p:

qoderclicn -p "Use the api-reviewer subagent to review this interface design"

Implicit invocation

Enter the task in natural language and let Qoder CN CLI pick a suitable Subagent to handle it. TUI mode: Qoder CN CLI decides based on each available Subagent's description:

Please do an interface design review for me

Headless mode: Pass the task description to qoderclicn -p, and Qoder CN CLI likewise picks a Subagent based on its description:

qoderclicn -p "Please do an interface design review for me"

Tip: If a specific Subagent must be used, prefer explicit invocation.

Use as main Agent for this session

--agent promotes a loaded Subagent to be the main Agent of the current session. The definition's initialPrompt becomes the initial prompt for the session. TUI mode: Specify --agent when starting the TUI:

qoderclicn --agent api-reviewer

Inside the TUI, this session uses api-reviewer as the main Agent. Invoking a Subagent from the /agents panel does not switch the main Agent—it triggers a single Subagent call via @agent-name. Headless mode: Combine with -p:

qoderclicn --agent api-reviewer -p "Review this interface design"

Orchestrate multiple Subagents

Describe the execution order of Subagents in natural language, and Qoder CN CLI follows that orchestration. TUI mode:

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

Headless mode:

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

If multiple tasks are mutually independent, request parallel scheduling explicitly. If there are dependencies, state the order as above. --max-turns is the total turn limit for the current headless query; to limit a single Subagent, set maxTurns in its configuration.

Custom Subagents

Create a locally persisted Subagent definition

Method 1: AI-assisted generation (recommended)

This is the easiest way to create a Subagent. Just describe your needs in natural language, and Qoder CN CLI generates the full configuration file. Steps:

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

> /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 entering a description, Qoder CN 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

Once generated, find the configuration file in the corresponding directory for further tuning:

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

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

Tip: Start with an AI-generated Subagent, then iterate to fit your specific needs. This quickly gives you a customizable baseline.

Method 2: Manual configuration (advanced)

For full control over the Subagent configuration, create a Markdown configuration file manually:

# Project level, effective for the current project only, suitable for committing to the repo
.qoder/agents/api-reviewer.md

# User level, effective for all projects of the current user
~/.qoder-cn/agents/api-reviewer.md

The Markdown file must start with a YAML frontmatter. The frontmatter declares configuration; the body is the system prompt for this local Subagent.

---
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 an isolated worktree, add to the frontmatter:

isolation: worktree

The file name does not determine the Subagent name; the actual name comes from the name field in the frontmatter.

Inject temporarily with --agents

--agents is suitable for headless mode, scripts, and one-off automation. It accepts a JSON object whose keys are Subagent names and values are the definition contents. Subagents injected via --agents are effective only for the current process and have the highest priority among same-name Subagents.

qoderclicn \
  --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, permissionMode. For timeoutMins, temperature, hooks, memory, background, or isolation, use Markdown configuration.

Configuring Subagents

Choose a scope

When creating or injecting a custom Subagent, you can pick the following scopes:

Scope	Configuration entry
Project	`.qoder/agents/*.md`
User	`~/.qoder-cn/agents/*.md`
Flag	`--agents`

Configure tools

Both tools and disallowedTools can be written as comma-separated strings or string arrays. Arrays support YAML inline arrays or YAML lists:

tools: Read,Grep,Glob

tools: [Read, Grep, Glob]

tools:
  - Read
  - Grep
  - Glob

Common tool names include Read, Grep, Glob, Bash, Write, Edit, WebFetch, WebSearch, Agent. MCP tools use fully qualified names:

tools:
  - mcp__docs__search
  - mcp__docs__*
  - mcp__*

To restrict a Subagent to invoking only specific Subagents, use the Agent(name) expression:

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

To disallow calling any Subagent, disable Agent:

disallowedTools: [Agent]

The tool set is processed in this order: first register available tools per tools, then remove tools per disallowedTools. For MCP tools, they must first be discovered via mcpServers or global MCP configuration, then allowed via tools, before the Subagent can use them.

Configure MCP

You can reference already-configured MCP services:

mcpServers:
  - docs

Or inline-define MCP services scoped to this Subagent only:

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

mcpServers supports both array format and object format. Inline service fields:

Field	Meaning
`command`	Command that starts the stdio MCP service
`args`	Command arguments array
`env`	Environment variables passed to the MCP service
`cwd`	Working directory for the MCP service
`url` / `http_url`	Remote MCP service address
`headers`	Remote request headers
`tcp`	TCP connection address
`type`	Transport type: `sse` or `http`
`timeout`	Connection or invocation timeout
`trust`	Whether to trust the MCP service
`description`	Service description
`include_tools`	Include only specified MCP tools
`exclude_tools`	Exclude specified MCP tools

Define Hooks

hooks written in Subagent frontmatter apply only to that Subagent's sessions. Supported events include PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, Notification. hooks does not support string shorthand. Each event's value must be a matcher array; each matcher declares one or more hooks via a hooks array. Stop in a Subagent maps to SubagentStop, i.e., it fires when the Subagent completes, not 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 has a set of matchers; the hooks under each matcher supports these types:

type	Required fields	Description
`command`	`command`	Runs a local command. Optional: `shell`, `timeout`, `if`, `statusMessage`
`http`	`url`	Calls an HTTP endpoint. Optional: `headers`, `allowedEnvVars`, `timeout`, `if`, `statusMessage`
`prompt`	`prompt`	Runs a model-based judgment using a prompt. Optional: `model`, `timeout`, `if`, `statusMessage`
`agent`	`prompt`	Runs judgment via an independent Hook Agent. Optional: `model`, `timeout`, `if`, `statusMessage`

The frontmatter schema also accepts once, but it is not preserved as one-time-hook semantics in ordinary Subagent frontmatter. For one-time behavior, control it in the hook command or external state.

Configure permission mode

permissionMode controls how Subagent tool calls are approved.

Value	Meaning
`default`	Uses default permission policy; asks when confirmation is required
`acceptEdits`	Automatically accepts edit operations
`bypassPermissions`	Skips permission confirmation. Downgrades to `acceptEdits` if the security policy disables this mode
`dontAsk`	Does not proactively ask; operations that require asking are rejected
`auto`	Uses automatic judgment for permissions
`plan`	Enables plan state for this Subagent, suitable for read-only planning

Use canonical values from the table for permissionMode. Runtime tolerates case, underscores, and hyphens. yolo is compatibly parsed as bypassPermissions, but public configuration should write bypassPermissions directly. Notes:

If permissionMode is not declared, the Subagent inherits the parent session's current mode.
If the parent session is already in acceptEdits, bypassPermissions, or auto, the Subagent cannot make its permissions more strict via its own configuration.
plan does not pollute the main session's plan state; it takes effect only in the Subagent's isolated context.

Configure remote Subagents

Remote Subagents are loaded via an Agent Card. They do not use the Markdown body as system prompt; instead, they use capabilities and descriptions exposed by the remote Agent Card.

---
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 Agent Card JSON. Remote Subagents support the auth field; common auth types include apiKey, http, and oauth. When authentication is required, place remote Subagents in user-level configuration to avoid committing credentials to the project repository.

Override existing Subagents via settings.json

settings.json cannot create new Subagents; it can only override already-discovered same-name Subagents. Currently supports overriding enabled state, model configuration, run limits, tool allowlist, and appending MCP services.

{
  "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 temporarily hide a Subagent.
Adjust model and temperature for a specific Subagent.
Constrain max turns or max execution time for automation.
Tighten the tool set without modifying the original Markdown.
Append MCP services to existing local Subagents.

Plugin-provided Subagents apply extra security policies: plugin Subagents' hooks, mcpServers, and permissionMode are removed, and only worktree is preserved for isolation.

Full field reference for local Subagents

The following fields apply to Markdown frontmatter. Unrecognized fields are ignored.

Field	Required	Values	Meaning
`name`	Yes	Non-empty string	Subagent name. Should be clear, stable, and easy to reference in natural language
`description`	Yes	Non-empty string	Purpose statement. Qoder CN CLI uses this to decide when to invoke the Subagent
`background`	No	Boolean	Whether to run in the background by default. Requires the current version to enable background Subagent sessions
`color`	No	red, blue, green, yellow, purple, orange, pink, cyan	Color shown when the Subagent runs in TUI
`disallowedTools`	No	String or string array	Tool blocklist; removes tools after registration
`effort`	No	low, medium, high, xhigh, max, or positive integer	Reasoning strength or budget
`hooks`	No	Hook configuration object	frontmatter hooks that apply only to this Subagent's sessions
`initialPrompt`	No	String	Initial prompt when this definition is used as the session's main Agent via `--agent`; ordinary Subagent calls do not inject it as a task prompt
`isolation`	No	Recommended: worktree	Isolation. `worktree` runs the Subagent in a separate git worktree; unset uses the default workspace
`kind`	No	local, remote	Type. Omitted means local Subagent; remote Subagent uses `remote`
`maxTurns`	No	Positive integer	Maximum conversation turns per Subagent invocation
`mcpServers`	No	Service name array, inline service object, or a combination	Additional MCP tools discovered for this Subagent. Final usage is still gated by tools/disallowedTools
`memory`	No	user, project, local	Persistent memory scope for this Subagent. Effective only when the global auto-memory capability is enabled
`model`	No	Any model name or alias; common values inherit, auto, lite, efficient, performance	The model used by the Subagent. Defaults to `inherit`, i.e., inherits the current session's model
`permissionMode`	No	default, acceptEdits, bypassPermissions, dontAsk, auto, plan	Permission mode for this Subagent. If not declared, inherits the parent session's current mode
`skills`	No	String or string array	Restricts the Skills usable by this Subagent
`temperature`	No	Number	Model temperature. If omitted, the loader writes the default temperature configuration
`timeoutMins`	No	Positive integer	Max execution time per Subagent invocation, in minutes
`tools`	No	String or string array; supports *	Tool allowlist. If omitted, uses the current available tool set; * means all tools

Testing the Setup

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

Run /agents reload or reopen the session.
Confirm it appears under the expected source in /agents or qoderclicn agents list.
Check that description clearly states when to invoke it.

Invoke it explicitly by name once:

Use the api-reviewer subagent to review the following interface:

POST /login
GET /logout

If configured with read-only tools, deliberately ask it "do not modify files, only output review results" and confirm no write operations occur.
If configured with disallowedTools, try asking it to use the disabled capability and confirm it either switches approach or returns a limitation notice.
If configured with MCP, check that the Subagent can discover the target MCP tools and that tools does not filter them out.
If background is configured or background execution is expected, confirm the main session does not wait for full results after task launch, and completion notifications arrive later.

If it is not being invoked, first switch to explicit invocation by name or @name. If it is still unavailable, check the loading errors in the /agents panel.

Best Practices

Give each Subagent a single, clear responsibility. Do not cram review, implementation, testing, and release into one prompt.
description is for scheduling decisions; the body prompt is for the Subagent itself. Both should be specific.
Grant read-only tools by default; add Edit, Write, or Bash only when writes are needed.
Set maxTurns, timeoutMins, and an explicit permissionMode for high-risk Subagents.
Use isolation: worktree when independent changes are needed; check the worktree path and actual diff after results return.
When relying on MCP tools, declare both mcpServers and tools to avoid discovering tools but not authorizing use.
Commit project-level Subagents to version control; keep user-level Subagents for personal preferences and cross-project workflows.
After modifying configuration, test with explicit invocation first, then rely on implicit dispatch.
For plugin-distributed Subagents, avoid depending on hooks, mcpServers, or permissionMode, which security policies may remove.

FAQ

What's the difference between a Subagent and the main conversation? Subagents run in an isolated context with their own system prompt, tool set, run limits, and permissions. Their results return to the main conversation, which synthesizes and replies to the user. Why doesn't the project-level Subagent I created appear? Confirm the file is at .qoder/agents/<name>.md, the frontmatter contains at least name and description, and the current project is trusted. After modifying, run /agents reload and check load errors in the /agents panel. Why doesn't my same-name Subagent take effect as expected? Higher-priority sources override lower-priority sources. Priority is Built-in < User < Project < Plugin < Flag. Use qoderclicn agents list to see shadowed entries. What is the difference between description and body prompt? description explains when to invoke the Subagent and affects scheduling. The body prompt is the system prompt the Subagent sees when invoked and affects how it does the task. Can I use multiple Subagents simultaneously? Yes. For mutually independent tasks, Qoder CN CLI can dispatch multiple Subagents concurrently. For tasks with dependencies, specify the order in the prompt. Can a Subagent invoke other Subagents? Yes, but the tool set must include Agent. To allow only specific Subagents, use Agent(name) or Agent(name1, name2). To completely disallow further scheduling, use disallowedTools: [Agent]. Why can't the Subagent use the MCP tool I configured? First confirm that the MCP service was discovered via mcpServers or global configuration, and that the corresponding tool name is allowed via tools. Writing only mcpServers does not automatically authorize all MCP tools. Why aren't the Subagent's permissions becoming more strict? If the parent session is already in acceptEdits, bypassPermissions, or auto, the Subagent cannot make its own permissionMode stricter. If permissionMode is not declared, the Subagent inherits the parent session's current mode. Where can I see background Subagent results? For background runs, the main session first receives a launch result. On task completion, a follow-up notification returns. Do not fabricate a summary based on expected results before completion. Can I edit built-in or plugin Subagents? Editing built-in or plugin Subagents directly is not recommended. To customize, create a user-level or project-level Subagent. If using same-name override, note source priority and plugin security policy.

​Quick Start

​What is a Subagent

​Built-in Subagents

​Viewing and Using Subagents

​View available list

​Sources and priority

​Explicit invocation

​Implicit invocation

​Use as main Agent for this session

​Orchestrate multiple Subagents

​Custom Subagents

​Create a locally persisted Subagent definition

​Method 1: AI-assisted generation (recommended)

​Method 2: Manual configuration (advanced)

​Inject temporarily with --agents

​Configuring Subagents

​Choose a scope

​Configure tools

​Configure MCP

​Define Hooks

​Configure permission mode

​Configure remote Subagents

​Override existing Subagents via settings.json

​Full field reference for local Subagents

​Testing the Setup

​Best Practices

​FAQ

Quick Start

What is a Subagent

Built-in Subagents

Viewing and Using Subagents

View available list

Sources and priority

Explicit invocation

Implicit invocation

Use as main Agent for this session

Orchestrate multiple Subagents

Custom Subagents

Create a locally persisted Subagent definition

Method 1: AI-assisted generation (recommended)

Method 2: Manual configuration (advanced)

Inject temporarily with --agents

Configuring Subagents

Choose a scope

Configure tools

Configure MCP

Define Hooks

Configure permission mode

Configure remote Subagents

Override existing Subagents via settings.json

Full field reference for local Subagents

Testing the Setup

Best Practices

FAQ