Custom subagents
Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system prompt, tool restrictions, and usage of models and agent skills.
When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. The subagent then works independently in its own context and returns the result to the main agent.
This page describes the benefits of using custom subagents, how custom subagents are invoked, adding your own subagents to Junie CLI, and what built-in tools are supported.
Why subagents?
With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler based on the nature of the request. Subagents let you:
Break down complex tasks into focused, single-purpose chunks that the main agent can delegate while keeping the subagent's context out of the main conversation.
Tailor and reuse agent's behaviour for specific tasks by defining coding standards, checklists, procedures, or agent skills to invoke and reusing these instructions across projects.
Optimize performance and costs by using lightweight models for simple repetitive tasks, or predefined models for specific types of tasks.
Enforce tool restrictions for specific types of tasks, such as restricting the agent to read-only operations for security auditing and reviews.
How Junie CLI uses subagents
Junie CLI invokes subagents automatically, informing the user which subagent has started working on the task.
The main agent discovers all available subagents, selects the relevant subagent by matching its name and description to the task at hand, runs it as a subtask, and brings the result back into the main session.
Configure subagent usage
Use /settings → Subagents to choose the subagents model selection policy. The setting is saved in ~/.junie/settings.json and applies to new sessions.
Mode | Behavior |
|---|---|
SameModelOnly | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents use the same model as the main agent, except custom subagents that set |
Auto | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. Custom subagents never get a model tier: they use their frontmatter |
The Subagents setting appears only when subagents are enabled in the current environment.
Run a custom agent standalone
Pass --agent <name> (or set JUNIE_AGENT=<name>) to run every regular prompt in the session through the named custom agent without consulting the task router:
Standalone --agent sessions work in interactive TUI, headless (--task/ positional task), and ACP modes with the following rules:
Classic session mode:
--agentlocks the session toClassicmode and cannot be combined with--agent-mode chat.Built-in commands still apply: explicit built-in workflows such as
--review,/plan, and direct shell commands still route to their dedicated built-in handlers.Parameter precedence: frontmatter
model,effort/reasoningLevel, andmaxTurnstake precedence over--model(JUNIE_MODEL),--effort(JUNIE_EFFORT), and--max-steps, falling back to those flags and session defaults when omitted.Unknown agent name: if
<name>does not match any discovered custom agent, the task fails immediately and lists the available agent names.
Creating a custom subagent
Subagents are Markdown files with optional YAML metadata stored in the .junie/agents/ or .agents/ directory. For example, a simple subagent file for a changelog assistant (.junie/agents/changelog.md) looks as follows:
File location
Junie CLI looks for custom subagent *.md files in the following locations:
Project scope:
<projectRoot>/.junie/agents/.Project scope:
<projectRoot>/.agents/.User scope:
~/.junie/agents/on macOS/Linux or%USERPROFILE%\.junie\agents\on Windows.User scope:
~/.agents/on macOS/Linux or%USERPROFILE%\.agents\on Windows.
Junie CLI treats Markdown files in these directories and their immediate subdirectories as subagent definitions, except files in skills/ directories. This includes frontmatterless files, so keep unrelated Markdown documents elsewhere.
File format
Subagent files contain a Markdown prompt body and may use YAML frontmatter for metadata.
An example subagent file that uses the commonly used supported frontmatter fields looks as follows:
Frontmatter fields
Field | Type | Required | Notes |
|---|---|---|---|
|
| no | The subagent name. If missing, the file name without the |
|
| no | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. If omitted (or if the file has no YAML frontmatter), Junie CLI uses the first non-heading paragraph of the Markdown body, truncated to 1,024 characters. |
|
| no | An allowlist of built-in tool groups. Also accepts a comma-separated string. If omitted or |
|
| no | A denylist of tool groups. Also accepts a comma-separated string. Applied after the |
|
| no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. |
|
| no | Model for this subagent (if supported by your environment). Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use |
|
| no | Permission mode applied to this subagent run. Allowed values: |
|
| no | Optional reasoning override for this subagent run. The |
|
| no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. When omitted, the main agent's step limit applies. |
|
| no | IDs/names of agent skills intended for this subagent. Currently, Junie reads this field but does not apply it: skills are neither preloaded nor restricted, and the subagent reads any skill available in the session on demand. |
|
| no | If |
Prompt body
In the prompt body, provide the instructions that define the agent's specialist persona, domain rules, workflow, and output format. Junie pairs this persona with its built-in file, search, shell, and engineering toolkit in both delegated subagent runs and standalone --agent sessions.
Tips
Make delegated work items as independent as possible.
Ask for specific outputs (for example, “return file paths and the exact symbol names”).
If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”).
Model, effort, and step limits
The frontmatter model, effort/reasoningLevel, and maxTurns apply both when the main agent delegates to the subagent and when you run it with --agent:
Main agent choices are ignored: the model tier and step limit that the main agent can request for delegated work do not apply to custom subagents.
Explicit model requests win over
model: if your environment lets the main agent pick exact models and you explicitly ask it to run a custom subagent on a specific model, that model replaces the frontmattermodelfor a new run, while the frontmattereffortstill applies.Continued runs keep their settings: when the main agent sends a follow-up to a running or finished subagent, the frontmatter
modelandeffortare applied again. A run that started on an explicitly requested model stays on that model.Omitted fields are inherited: without
model,effort, ormaxTurns, the subagent uses the main agent's model, reasoning level, and step limit.Typos are silent in the session: an unrecognized
modelonly produces a warning in the log, and the subagent runs on the main agent's model. Check the log once after adding or editing an agent, or run it briefly withjunie --agent <name>to confirm the model.The model must be reachable: a specific
modelis used as is, without falling back to the main agent's model. If your provider or API key cannot serve that model, the subagent run fails. Only thesmallalias falls back to the main agent's model when no small model is available.
Supported tool groups
Custom subagents can define which tool groups are allowed (tools) or forbidden (disallowedTools) during task execution.
If the tools field in the YAML frontmatter is present, non-empty, and does not contain "*", only the specified groups are allowed, with the rest being banned by default. There's no need to disallow them explicitly using the disallowedTools field.
The "*" wildcard is supported only in tools, not in disallowedTools.
If tools is an empty list (tools: []), the subagent gets no tools from the built-in groups below but retains MCP tool access subject to mcpServers and existing permissions. Status, result, and MCP activation actions remain available, as does agent_skill_read_doc when skills are enabled and available. The palette is therefore not strictly MCP-only and differs from GitHub Copilot's empty-list semantics, which disable all tools.
There are two types of tools that can be either allowed or banned:
Built-in tool groups.
Tools provided by MCP servers (if available in your environment).
The built-in tool group labels are:
Built-in tool group label | What it enables |
|---|---|
| Read-only file viewing actions (open/scroll). |
| Running shell commands in the local environment. |
| Searching for files by path pattern ( |
| Searching for text by regular expression ( |
| Creating new files. |
| Modifying existing files (search/replace, multi-edit, apply patch, undo). |
| Searching the web or fetching URLs for up-to-date information. |
| Fetching content from a specific URL. |
| Asking the user for input or a choice. |
Exact group labels take precedence. Other spellings of group labels are accepted case-insensitively as aliases, except that edit (unlike exact Edit) enables both Edit and Write. For compatibility with GitHub Copilot agent profiles, Junie CLI also accepts these case-insensitive aliases and ignores unrecognized names:
execute,shell,powershell:Bash.read,notebookread:Read.edit,multiedit,notebookedit:EditandWrite.search:GlobandGrep.web:WebSearchandWebFetch.
Example of a read-only subagent allowed to search for a text by regular expression:
Inside a Git repository, Glob and Grep skip files ignored by .gitignore. Outside a Git repository, they scan the directory directly.
Limitations
Results come back as a final summary: delegated subagents and headless runs finish with a final summary rather than a conversational reply. Describe the expected result format in the prompt body.
--resumeneeds--agentagain: when you resume a session in a new Junie CLI process, pass--agent <name>(or setJUNIE_AGENT) again. Otherwise, new prompts go to the default main agent; only an interrupted turn continues on the custom agent.No delegation from
--agentsessions: a custom agent running as the session's main agent cannot delegate work to other subagents.--system-promptis not passed to subagents: it applies only to the session's main agent, including a custom agent started with--agent.