Sub-agents

What this accomplishes

The sub-agent system: a generic registry of named sub-agents invoked via @ mentions, running as background agent sessions with their own system prompts and tool access.

A sub-agent is a background agent session that runs while the main session continues. The sub-agent has its own system prompt, its own tool calls, and its own model. The sub-agent reports its output back to the main session when it finishes.

This page is the sub-agent system in detail. The high-level introduction is in the overview.

Current availability

This page documents behaviour verified in Miton development builds. Miton is still pre-release and is not publicly downloadable; invited beta users will receive a signed desktop build with automatic updates.

Before you start

• A Miton development build and an active project containing source code.
• A connected model. Trust the project before allowing file, terminal or Git actions.

The registry

Sub-agents are stored in a SubagentRegistry (packages/subagent/). Each sub-agent is a SubagentDefinition with a name, a display name, a description, a system prompt template, a set of allowed tools, and optional model and token-budget overrides.

The registry is populated at startup from bundled markdown files with YAML frontmatter. Users and plugins can register additional sub-agents at runtime.

The five default sub-agents

Miton ships with five default sub-agents. Each is a prompt template registered in the SubagentRegistry at startup.

Explorer

The Explorer reads the codebase to answer a question. The Explorer does not write files. The Explorer is the right choice when the user wants a quick map of the code or a specific question answered.

Tools: read, glob, grep. Model preference: fast.

Verifier

The Verifier runs the project’s tests, type-checker, and linter to verify code correctness. The Verifier does not write code.

Tools: read, glob, grep, bash. Model preference: fast.

Debugger

The Debugger investigates a failing test or a runtime error. The Debugger can run shell commands to reproduce the issue, form hypotheses, and propose a fix.

Tools: read, glob, grep, bash. Model preference: reasoning. Max output: 16 384 tokens.

Test Runner

The Test Runner runs the project’s tests, analyses failures, and suggests fixes for failing tests.

Tools: read, glob, grep, bash. Model preference: default. Max output: 8 192 tokens.

Orchestrator

The Orchestrator plans and coordinates multi-step tasks. It can read, write, run shell commands, and ask clarifying questions.

Tools: read, glob, grep, bash, write, question, todo. Model preference: reasoning. Max output: 32 768 tokens.

How to spawn a sub-agent

Sub-agents are spawned via @<name> mention dispatch. Type @explorer, @verifier, @debugger, @test-runner, or @orchestrator in the message composer (or in a chat message) followed by the task description. The mention parser resolves the name against the SubagentRegistry and spawns a background agent session.

Example: @explorer where is the user authentication code?

The sub-agent runs as a background session. The main session is not blocked. When the sub-agent finishes, its output is injected into the chat as a synthetic assistant message. The output is also stored in the subagentStore for the Agent Manager Dashboard.

How sub-agents execute

A spawned sub-agent runs as a background agent session:

1. The system prompt template is populated with the task description ({{task}} replacement).
2. A agent loop is created with the sub-agent’s allowed tools and model.
3. The agent loop runs up to 15 turns (configurable per sub-agent).
4. Output is capped at the sub-agent’s maxOutputTokens limit (if set).
5. A hard USD cost ceiling can be enforced via the maxCost option.
6. When the loop finishes, the result is reported back via callbacks.

The sub-agent’s session is independent of the main session. The main session’s context, tools, and model are not affected.

The Agent Manager Dashboard

The Agent Manager Dashboard (components/agent/AgentManagerDashboard.tsx) shows all sub-agent runs for the current project. Each run displays:

• Status — running, completed, failed, or cancelled.
• Output — the sub-agent’s text output.
• Cost — the model cost (if reported by the provider).
• Duration — wall-clock time from start to finish.

The dashboard is the audit trail for sub-agent work. The user can review what each sub-agent did, what it cost, and whether it succeeded.

What the sub-agent system does not cover

• Worktree isolation — write-capable sub-agents take an exclusive lease on the active worktree. If the lease is held, Miton creates an isolated git worktree under .miton/worktrees/ and opens an Apply / Discard / Keep review when the run finishes. Read-only sub-agents share the active checkout.
• Per-sub-agent permission gates — sub-agents use the same permission policy as the main session. There is no per-sub-agent policy override in the current implementation.
• User-defined sub-agent files — there is no .miton/subagents/ directory convention. Custom sub-agents are registered programmatically via the SubagentRegistry API or by plugins.

What success looks like

Sub-agents are background agent sessions you spawn with @<name> mentions. There are five defaults: Explorer (code reading), Verifier (tests and lint), Debugger (failure investigation), Test Runner (continuous testing), and Orchestrator (multi-step coordination).

The sub-agent runs in the background; the main session continues. When it finishes, the output appears in the chat and in the Agent Manager Dashboard. Write-capable sub-agents take a worktree lease (or an isolated .miton/worktrees/ checkout when the lease is busy); read-only agents share the active checkout.

Common failures and recovery

• Confirm the correct project and branch are active.
• Check the model connection and the permission request shown in Chat.
• Keep the exact error before retrying; use Code troubleshooting when the failure persists.

Related next action

Open Code troubleshooting for recovery steps and diagnostic paths.