Subagents
The agent hands large, separable work to subagents in the background — the main conversation keeps going, and results come back when done.
A subagent is another agent that the agent sends off: it handles a self-contained piece of work in its own context and hands back only the conclusion. The files it read and the attempts it made never crowd your main conversation.
When one is used
You don't start them by hand — the agent dispatches one when it judges it worthwhile. You can also just say "send a subagent to look into…".
- Explore — when it's unclear where code lives or the call chain runs deep, a read-only explore agent searches and returns the conclusion plus the key file locations. Several independent questions can run in parallel.
- Task agents — large, separable work (a whole subsystem, a refactor across many files) runs in the background while the main agent keeps going; you get a notice and a list of changed files when it finishes.
Built-in types
| Type | What it can do |
|---|---|
code | Edit code, no commands (default) |
shell | Edit code and run commands and tests |
plan | Read-only, for design work |
research | Deep research; writes only a requirements document |
verify | Runs and verifies changes; can execute but not write files |
online | Drives the built-in browser for web tasks; stops at payment / login / captcha |
Limits
- At most 3 subagents run at once; extra ones are not created
- There are no file locks between subagents, so the agent splits work by file to keep two of them off the same file
- A regular subagent only sees a short excerpt of recent messages, so any background it needs goes into the task description
Custom roles
Put a Markdown file in ~/.neox/agents/ (global) or <project>/.neox/agents/ (this project):
---
name: auditor
description: Read-only security audit
base: plan
---
Focus on auth, injection and leaked secrets; give a file and line for every issue.The body is the role's prompt. base is one of the built-in types above and decides which tools it gets; add model: <model ID> to pick a model, or leave it out to use the main agent's model. Changes take effect immediately, no restart; names can't clash with built-in types.
Platform support
| Platform | Supported |
|---|---|
| Desktop | ✓ |
| CLI | ✓ |