Subagents

A subagent is a specialized agent that the primary Agent can launch to handle work in its own isolated context, then summarize the results back into the main conversation. ZCode ships with built-in general-purpose and Explore subagents, and you can now define your own user-level subagents from Settings.

When the primary Agent decides a task needs isolated context or parallel research, it launches a subagent through the Agent tool. The subagent works in its own context and reports its findings back so the primary Agent can keep moving.

Built-in: General-Purpose Subagent

general-purpose is the default built-in subagent for broad tasks. It has access to all tools, so it is a good fit when the primary Agent needs an isolated context that can read, edit, run commands, or carry a self-contained piece of work forward.

Good general-purpose tasks include:

• Implementing a small feature or fixing a clear issue independently.
• Organizing files, running verification commands, and reporting results from another context.
• Splitting parallel documentation, code, or configuration work into a separate task.

If a task only needs read-only research, evidence gathering, or call-chain mapping, prefer Explore below.

Built-in: Explore

Explore is a read-only file-search and codebase-research specialist for broad code search, call-chain investigation, architecture discovery, and evidence gathering.

Explore is read-only. It does not create, modify, move, or delete files. It mainly uses read and search tools, such as reading files, matching file names, searching file contents with regex, and, when needed, reading known URLs or searching external information.

Good Explore tasks include:

• Finding where a capability is implemented.
• Mapping module entry points, call chains, and key dependencies.
• Researching related code and risks before making changes.
• Searching across multiple directories, naming patterns, or implementation paths in parallel.

You can ask ZCode to use Explore directly in your prompt, for example:

First use Explore to research this module's call chain, then summarize the main entry points and risks.

Search for where this feature is implemented in read-only mode, and list the related files and evidence.

Custom Subagents (Beta)

Beta — User-level custom subagents are rolling out. The capability and its scope may still change.

You can now create your own subagents from Settings -> Subagents. A custom subagent lets you package a reusable role — a reviewer, a test writer, a docs researcher — with its own model, tool permissions, and instructions, and reuse it across tasks.

In the Subagents panel you can:

• View the available subagents, including the built-in general-purpose (the default role, with access to all tools) and Explore (read-only search).
• Create a subagent by filling in its name, color, model, description, available tools, and system prompt.
• Edit, delete, enable, or disable the subagents you have created (built-in roles are shown for reference and cannot be edited or deleted).

Create A Subagent

Click New in the top-right corner and configure the reusable role in the form:

When you save, ZCode writes the subagent as a Markdown file under ~/.zcode/agents/<name>.md, and the ZCode Agent runtime loads it on the next run. Once enabled, you can let the Agent pick the subagent automatically, or reference it with @ in the chat box.

Scope and Limits

• User-level only. The current Beta manages global / user-level subagents stored under ~/.zcode/agents/. Creating or editing workspace / project-level subagents from Settings is not available yet.
• Built-in roles are read-only. general-purpose and Explore are shown for reference but cannot be edited or deleted, and their names cannot be reused.
• Foreground execution. Subagents run in the foreground — when several are launched together they run in parallel, and the main task waits for them to finish before continuing. Background execution is not enabled yet.

Next Steps