Multi-agent.
When a task is big enough, Nilux can delegate parts of it to subagents — separate LLM contexts that work independently and return a result. The main agent picks the right agent type for the job based on the task. Each agent type has its own predefined set of tools and capabilities.
How it works
You write a message. The agent decides the task is complex enough to delegate. It calls the Task tool internally, choosing which agent type fits best (e.g. Explore for research, a custom architect for planning). The subagent runs with the tools defined in its agent definition — not chosen ad-hoc by the main agent. You see progress in real time. When it finishes, the main agent reads the result and continues.
bash❯refactor the auth module to use JWT refresh tokens, then write tests> Task · Explore · analyzing current auth implementation└ grep · 3 calls · read · 5 calls✓ done · 12.4s · 24k tokens> Task · executor · refactoring auth module└ edit · 4 files · bash · 2 calls✓ done · 38.1s · 67k tokens
There is no explicit command to spawn an agent. The LLM decides when delegation makes sense. If you want to force it, just be direct: "use an agent to explore the billing module".
Built-in agents
Two agent types ship with Nilux:
- Explore — read-only. Tools: Read, Glob, Grep, Bash. Cannot write or edit files. Fast and cheap for codebase research.
- Task — full access. All tools except memory writes, recursive spawning, user prompts, and image generation. For multi-step implementation work.
Neither can spawn its own subagents — no recursion by design.
Custom agents
Drop a .md file in ~/.nilux/agents/ (global) or .nilux/agents/ (project). YAML frontmatter defines the agent, the body is its system prompt:
markdown---name: architectdescription: Plans implementation before writing codemodel: Nilux Protools: Read, Grep, Glob, Bash, Writecolor: purpledisallow-background: true---You are the Architect. Analyze the codebase, identifythe right files, and write a detailed PLAN.md beforeany code changes. Never edit code directly.
Frontmatter fields:
name— unique identifier (defaults to filename)description— shown to the LLM when choosing which agent to usemodel— which model tier to use (Standard or Pro)tools— allowed tools (Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite)disallowed_tools— explicitly blocked toolscolor— UI color (red, blue, green, yellow, purple, orange, pink, cyan)disallow-background— prevent this agent from running in background mode
Changes to agent files are picked up automatically — no restart needed. Project agents override global agents with the same name.
Use /agents inside a session to create, edit, and assign models to agents through a visual UI — no need to edit files manually.
Parallel execution
When the LLM calls multiple Task tools in one response, they run in parallel. You see progress for each agent simultaneously in the UI. This happens naturally when the agent recognizes independent sub-tasks:
bash❯write tests for both the auth and billing modules> Task · executor · writing auth tests> Task · executor · writing billing tests└ both running in parallel✓ auth tests · 31.2s✓ billing tests · 44.7s
Background agents
The LLM can spawn agents with run_in_background: true. Background agents have restricted tools (read-only: Read, Grep, Glob, WebSearch, WebFetch) and don't require approval for operations. Their results are written to ~/.nilux/bg-tasks/ and the main agent receives a notification when they finish.
You can also move a running foreground task to background with Ctrl+B. The bottom bar shows counts of active background workflows, shells, and agents.
Workflows
Workflows are a structured multi-agent pattern with a fixed pipeline: Planner → Coder ↔ Reviewer. The Planner creates an implementation plan, the Coder executes it, and the Reviewer checks the result. If the Reviewer finds issues, it sends the Coder back for fixes — up to 5 iterations.
Each role has a fixed system prompt and tool set. Agents communicate through structured handoff verdicts (plan_ready, ready_for_review, approved, needs_fixes).
Configure workflow role models with /workflow config.
Multi-agent is worth it when a task can be split into independent sub-tasks. It parallelises wall-clock time but runs multiple contexts at once — each agent burns its own tokens.