Документация доступна только на английском языке.
Agents
Define subagents in Markdown with frontmatter, in the format your existing agent files already use, and delegate work to them with fresh context.
A subagent is a separate agent the main agent can hand a task to. It starts with a clean context, does its work with its own tools and instructions, and returns a report. The main conversation receives only the conclusion, not every file the subagent read.
Use subagents for:
- Research across many files where you only need the answer.
- Independent work in parallel. The agent can start several subagents in one step.
- Specialized roles with their own prompt, tools and model: a reviewer, a test writer, a documentation checker.
Defining an agent
A subagent is a Markdown file. The frontmatter configures it; the body is its system prompt.
---
name: reviewer
description: Reviews a diff for correctness bugs. Use after making non-trivial changes, before reporting the work as done.
tools: Read, Grep, Glob, Bash
model: anthropic:claude-opus-5-5
effort: high
---
You review code changes for correctness. You never edit files.
1. Run `git diff` to see the changes.
2. For each change, read enough surrounding code to understand it.
3. Report bugs first, most severe first, each with file:line and a concrete failure scenario.
4. Then list simplifications, briefly.
If you find nothing wrong, say so plainly. Don't invent issues.Where agents live
| Scope | Directories |
|---|---|
| Project | .nib/agents/, .claude/agents/ |
| User | ~/.nib/agents/, ~/.claude/agents/ |
Project agents override user agents with the same name, and .nib/ overrides .claude/ at the same level. Files that can't be used are reported with the reason; they are never silently skipped.
Frontmatter
| Field | Type | Meaning |
|---|---|---|
name | string | Required. The agent type, used in Agent(…) calls and rules |
description | string | Required. When the main agent should use it |
tools | list | Tools it may use. Omit to inherit the main agent's tools |
disallowedTools | list | Tools it may not use |
model | string | Model to run on, as provider:model or a bare id. Omit to inherit |
effort | string | none, minimal, low, medium, high, xhigh or max |
permissionMode | string | default, acceptEdits, plan, auto, dontAsk or bypassPermissions |
maxTurns | number | Stop after this many model turns |
isolation | worktree | Always run in its own git worktree. Without it, a writing agent gets one when it runs in the background or beside another writer (see below) |
background | boolean | Run in the background in headless runs too. In a session you follow, every agent already does |
skills | list | Skills to preload |
mcpServers | list | MCP servers it can use: names of configured servers, or inline definitions |
hooks | object | Hooks active while it runs. A Stop hook here becomes SubagentStop |
memory | user, project or local | Scope of the agent's persistent memory directory, where it can keep notes between runs. A folder reached through a symbolic link isn't used: the agent runs without memory, and you're told |
omitClaudeMd | boolean | Skip instruction files entirely, for a clean-room agent |
initialPrompt | string | The first message when you start a new CLI session as this agent (--agent <name>) without a prompt. Not used when it runs as a subagent |
tools accepts a comma-separated string or a YAML list of tool names. An entry written as a rule, such as Bash(git diff *), names the whole tool: the agent gets all of Bash, and in disallowedTools it loses all of Bash. Agent(type, …) is the exception: it's kept as written and grants no Agent tool. To limit how an agent uses a tool, use permission rules.
How the main agent uses them
The main agent calls the Agent tool:
| Input | Meaning |
|---|---|
description | A short label shown in the UI |
prompt | The full task. The subagent can't see your conversation, so this must stand on its own |
subagent_type | Which agent to use. Defaults to general-purpose |
model | Override the agent's model for this call |
isolation | worktree to give it its own git worktree |
name | A name for addressing it later with SendMessage |
In a session you follow, agents run in the background: the call returns at once, the main agent keeps working, and it's notified when each one finishes. Headless runs (scripts, CI) wait for each report, unless the call sets run_in_background: true or the agent's definition sets background: true.
A subagent that can write files gets its own git worktree when it runs in the background or beside another writer, and its changes stay separate until they're merged; isolation: worktree gives it one every time. Only a headless run's foreground writer, with no other agent writing, works in your folder. Outside a git repository, writers share the folder. See Parallel agents.
You can ask for a specific agent in your prompt ("use the reviewer agent to check this"), and the agent will usually pick a suitable one on its own based on the descriptions.
Writing a good description
The description decides when the agent gets used. Write it as an instruction to the main agent:
- Good: "Reviews a diff for correctness bugs. Use after making non-trivial changes, before reporting the work as done."
- Weak: "Code review expert."
Permissions
Subagents run under the same permission engine as the main agent. Their tool calls are checked against your rules, and prompts appear in the same place. Restrict which agents may be started with rules such as Agent(reviewer) in deny or ask. An Agent(…) rule in allow changes nothing: outside auto mode every agent may start anyway, and in auto mode the classifier judges every start.
A subagent's report reaches the main agent as information, not as instructions from you. It can't grant itself or the main agent new permissions.
Messaging between agents
Agents can talk to each other with SendMessage, addressed by name, handle or session id, and discover each other with ListAgents. This works between subagents and between separate sessions running on the same daemon. Messages are visible in the session log.
Models for subagents
A subagent can run on a different model from the main agent, even from a different provider. Common patterns:
- A fast, inexpensive model for broad searches and summaries.
- A different frontier model as a reviewer, so a second model family checks the first one's work.
- The same model at higher effort for the hardest sub-problem.