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 custom subagents automatically. The main agent can discover and call a custom subagent on its own if it deems the subagent to be relevant to the current task.

The main agent selects the custom agent by matching its name and description to the work at hand, runs it as a subtask, and brings the result back into the main session.

Creating a custom subagent

Subagents are Markdown files with YAML metadata stored in the .junie/agents/ directory. For example, a simple subagent file for a changelog assistant (.junie/agents/changelog.md) looks as follows:

---
name: "changelog"
description: "Write a changelog entry for a PR"
---

You are a changelog assistant.

Given the PR title and description, produce a short changelog entry.

File location

Junie CLI looks for custom subagent *.md files in two locations:

Project scope: <projectRoot>/.junie/agents/.
User scope: ~/.junie/agents/ on macOS/Linux or %USERPROFILE%\.junie\agents\ on Windows.

File format

Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt.

An example subagent file that uses all available frontmatter fields looks as follows:

---
description: "Review a change and propose a safe patch"
name: "code-review-helper"
tools: ["Read", "Grep", "Edit"]
disallowedTools: ["Bash", "WebSearch"]
model: "sonnet"
skills: ["kotlin", "writerside"]
allowPromptArgument: true
---

You are a careful code reviewer.

Context:

- File: $path
- Focus area: $focus

Tasks:

1) Explain the issue concisely.
2) Propose a minimal fix.
3) If edits are needed, prepare a small patch.

If you need additional context, ask for it.

Frontmatter fields

Field	Type	Required	Notes
`name`	`String`	no	The subagent name. If missing, the file name (without extension) is used. Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens).
`description`	`String`	yes	The subagent description. Used by the main agent to decide when to delegate a task to this subagent.
`tools`	`List<String>`	no	If present and non-empty: an allowlist of tool groups.
`disallowedTools`	`List<String>`	no	A denylist of tool groups. Applied after the `tools` filtering.
`model`	`String`	no	Model override for this subagent run (if supported by your environment). Accepted values depend on your environment; some builds also support aliases like `sonnet`, `opus`, `grok`.
`skills`	`List<String>`	no	IDs/names of agent skills to load for the subagent worker (if supported by your environment).

Prompt body

In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the instructions delegated from the main agent.

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”).

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 and non-empty, 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.

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`	Read-only file viewing actions (open/scroll).
`Bash`	Running shell commands in the local environment.
`Glob`	Searching for files by path pattern (`glob`).
`Grep`	Searching for text by regular expression (`grep`).
`Write`	Creating new files.
`Edit`	Modifying existing files (search/replace, apply patch).
`WebSearch`	Searching the web for up-to-date information.
`AskUserQuestion`	Asking the user for input or a choice.

Example of a read-only subagent allowed to search for a text by regular expression:

---
name: "symbol-finder"
description: "Find where a symbol is used and summarize"
tools: [ "Read", "Grep" ]
---

04 March 2026