Junie Help

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 model in their frontmatter.

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 model, or the main agent's model when it is omitted. This is the default mode.

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:

junie --agent code-review-helper "Review my staged changes"

Standalone --agent sessions work in interactive TUI, headless (--task/ positional task), and ACP modes with the following rules:

  • Classic session mode: --agent locks the session to Classic mode 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, and maxTurns take 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:

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

--- description: "Review a change and propose a safe patch" name: "code-review-helper" tools: ["Read", "Grep", "Edit"] disallowedTools: ["Bash", "WebSearch"] mcpServers: ["github"] model: "sonnet" reasoningLevel: "high" maxTurns: 20 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 the .md or .agent.md extension is used. Uppercase letters are converted to lowercase and whitespace is replaced with hyphens (-).

After normalization, must match: [a-z0-9][a-z0-9_-]* (starts with a lowercase letter or digit, followed by lowercase letters, digits, hyphens, or underscores).

description

String

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.

tools

List<String>

no

An allowlist of built-in tool groups. Also accepts a comma-separated string. If omitted or ["*"], all built-in tools are available. An empty list ([]) disables these groups without disabling MCP tools or skill-document loading when enabled.

disallowedTools

List<String>

no

A denylist of tool groups. Also accepts a comma-separated string. Applied after the tools filtering.

mcpServers

List<String>

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.

model

String

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 /model, or use a name accepted by the --model CLI flag. Some builds also support aliases like sonnet, opus, grok, and custom model profile IDs in the custom:<profile-id> format. The agent-only alias small selects the small model of the main agent's provider. Tier names such as fast or premium are not valid values. An unrecognized value is ignored with a warning in the log, and the main agent's model is used instead. See Model, effort, and step limits and Model selection.

permissionMode

String

no

Permission mode applied to this subagent run. Allowed values: default, acceptEdits, dontAsk, bypassPermissions, plan. Defaults to default.

reasoningLevel

String

no

Optional reasoning override for this subagent run. The effort key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as low, medium, or high, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. An unknown level makes Junie skip the whole agent file with a warning in the log; a known level that the effective model does not support makes the run fail with an error listing the supported levels.

maxTurns

Int

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.

skills

List<String>

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.

allowPromptArgument

Boolean

no

If true, Junie exposes an additional $prompt argument to the subagent prompt. When $prompt is not referenced explicitly in the prompt body, the delegated user request is appended automatically as User Input: ....

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 frontmatter model for a new run, while the frontmatter effort still applies.

  • Continued runs keep their settings: when the main agent sends a follow-up to a running or finished subagent, the frontmatter model and effort are applied again. A run that started on an explicitly requested model stays on that model.

  • Omitted fields are inherited: without model, effort, or maxTurns, the subagent uses the main agent's model, reasoning level, and step limit.

  • Typos are silent in the session: an unrecognized model only 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 with junie --agent <name> to confirm the model.

  • The model must be reachable: a specific model is 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 the small alias 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

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, multi-edit, apply patch, undo).

WebSearch

Searching the web or fetching URLs for up-to-date information.

WebFetch

Fetching content from a specific URL.

AskUserQuestion

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: Edit and Write.

  • search: Glob and Grep.

  • web: WebSearch and WebFetch.

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" ] ---

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.

  • --resume needs --agent again: when you resume a session in a new Junie CLI process, pass --agent <name> (or set JUNIE_AGENT) again. Otherwise, new prompts go to the default main agent; only an interrupted turn continues on the custom agent.

  • No delegation from --agent sessions: a custom agent running as the session's main agent cannot delegate work to other subagents.

  • --system-prompt is not passed to subagents: it applies only to the session's main agent, including a custom agent started with --agent.

19 November 2026