> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```text theme={null} 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. | | `SaveMemory` | Memory management enabled | Manages cross-session memories, preferences, and facts. | 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: ```text theme={null} /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: ```text theme={null} /agents reload ``` #### Non-Interactive In non-interactive environments, use: ```bash theme={null} 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: ```text theme={null} Use the api-reviewer subagent to review this API design ``` You can also mention a loaded Subagent with `@` in TUI input: ```text theme={null} @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`: ```bash theme={null} 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`: ```text theme={null} Review this API design ``` #### Headless Mode In Headless mode, pass only the task description through `qodercli -p`: ```bash theme={null} 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: ```bash theme={null} 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`: ```bash theme={null} 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: ```text theme={null} 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`: ```bash theme={null} 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. ```text theme={null} > /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: ```text theme={null} > /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: ```bash theme={null} # 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: ```bash theme={null} # 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. ```markdown theme={null} --- 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: ```yaml theme={null} 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. ```bash theme={null} 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: ```yaml theme={null} tools: Read,Grep,Glob ``` ```yaml theme={null} tools: [Read, Grep, Glob] ``` ```yaml theme={null} tools: - Read - Grep - Glob ``` Common tool names include `Read`, `Grep`, `Glob`, `Bash`, `Write`, `Edit`, `WebFetch`, `WebSearch`, and `Agent`. MCP tools use fully qualified names: ```yaml theme={null} tools: - mcp__docs__search - mcp__docs__* - mcp__* ``` To allow a Subagent to call only specific other Subagents, use the `Agent(name)` expression: ```yaml theme={null} tools: - Read - Grep - Agent(Explore, Plan) ``` To prevent further Subagent dispatch entirely, disable `Agent`: ```yaml theme={null} 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: ```yaml theme={null} mcpServers: - docs ``` Or define an MCP server inline for this Subagent: ```yaml theme={null} 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. ```yaml theme={null} 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. ```markdown theme={null} --- 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. ```json theme={null} { "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: ```text theme={null} 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/.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.