What is a Consilium sub-agent?

A reusable, scoped persona stored as a Markdown file with YAML frontmatter. Each sub-agent has its own model, allowed-tools list, and system prompt. The CLI launches a sub-agent in a fresh context window so it cannot see (or leak) the parent conversation.

Where do sub-agent files live?

In ~/.consilium/agents/ .md for user-scoped agents and ./.consilium/agents/ .md for repo-scoped agents. Repo-scoped definitions take precedence over user-scoped definitions with the same name.

Can I restrict which tools a sub-agent uses?

Yes. The allowed-tools YAML field is a strict allowlist; the sub-agent cannot call any tool not on the list. Omit the field for full access. The reviewer example below restricts to Read, Grep, and Glob - it cannot Write, Edit, or run Bash.

Does a sub-agent share the parent's context?

No. Sub-agents start in a fresh context window with only the system prompt from the frontmatter plus the user prompt you passed. This is by design: a tightly-scoped sub-agent for code review should not see your debate transcript or unrelated files.

Which models can a sub-agent use?

Any model alias the CLI recognizes, e.g. claude-sonnet-4-6, claude-haiku-4-5-20251001, gpt-5.5, gemini-3.1-pro-preview. Omit the model field to inherit the CLI default. Use a smaller model for cheap, repeatable sub-agents like linters.

Back to CLI

Sub-Agents

Q: How do I invoke a sub-agent?

From the shell: `consilium sub-agent reviewer 'audit the auth flow in src/auth/'`. Inside chat: type the /sub-agent slash command and pick from the list. To enumerate all available sub-agents: `consilium sub-agents list`.

Sub-agents are user-definable, tool-scoped personas you can call by name from the Consilium CLI. Drop a Markdown file with YAML frontmatter into ~/.consilium/agents/, then invoke with consilium sub-agent <name> <prompt>. Each runs in a fresh context with its own model, system prompt, and tool allowlist.

Why sub-agents?

A 2024 study of multi-agent systems by Park et al. observed that isolating an agent to a single tool set reduces hallucinated tool calls by roughly 38 percent compared to a general-purpose agent. Sub-agents apply that principle locally: a code-review sub-agent that can only Read/Grep cannot fabricate a Bash command, because Bash is not in its allowed-tools list. The fresh-context guarantee also prevents prompt-injection bleed from a parent conversation into a sensitive task.

The pattern mirrors Anthropic's Claude Code sub-agents specification so existing definitions are largely portable. Consilium adds a multi-model dimension: a sub-agent file can pin itself to GPT, Claude, Gemini, or any registered alias.

Where do I create a sub-agent?

Two locations are scanned, repo-scoped first then user-scoped:

./.consilium/agents/<name>.md - repository-local. Check into version control to share with teammates.
~/.consilium/agents/<name>.md - your personal collection. Available in every project.

If both directories define a sub-agent with the same name, the repo-scoped definition wins so projects can override personal defaults.

What does the YAML frontmatter look like?

Field	Required	Description
name	yes	Unique identifier. Used in invocation: `consilium sub-agent <name>`.
description	yes	One-line summary shown by `sub-agents list` and the /sub-agent picker.
model	no	Model alias (e.g. claude-sonnet-4-6). Defaults to the CLI default model.
allowed-tools	no	Array of tool names. Acts as a strict allowlist when present.
system	no	Inline system prompt. If omitted, the Markdown body is used.

---
name: reviewer
description: Read-only code reviewer focused on auth, input validation, and secrets.
model: claude-sonnet-4-6
allowed-tools: [Read, Grep, Glob]
---
You are a senior application security engineer. Your job is to read code
in the user's workspace and report any issues you find related to:
- Authentication and session handling
- Input validation and SQL/command/HTML injection
- Secret handling and configuration leakage

Output findings as Markdown with three sections: Critical, High, Notes.
Each finding must cite file:line and quote the offending code.

How do I invoke a sub-agent?

From the shell:

consilium sub-agents list
consilium sub-agent reviewer "audit src/auth and report findings"
consilium sub-agent reviewer "audit src/auth" --json

Inside an interactive chat REPL, the /sub-agent slash command opens a picker:

> /sub-agent
1. reviewer    - Read-only code reviewer
2. summarizer  - Summarize the current selection
3. test-writer - Generate Vitest cases for selected file
Select [1-3]: 1
Prompt for reviewer: audit src/auth

Tool scoping (least-privilege)

When allowed-tools is present, it is a strict allowlist. If the sub-agent attempts to call a tool not in the list, the CLI rejects the call and logs a violation. Omit the field for full access. Three common presets:

Read-only review: [Read, Grep, Glob]
Single-file editor: [Read, Edit]
Local shell only: [Bash, Read]

Reference

The agent loader, frontmatter parser, and invocation pipeline live in the public CLI repository: github.com/skadri1601/consilium-cli. See the sandbox docs for combining sub-agents with OS-level isolation.