Agents
Agents are defined in packages/nikcli/src/agent/agent.ts and configured through nikcli config overlays.
Primary Agents
ralph
Conversational primary agent intended for lighter interactive work.
build
Default coding agent with the broadest tool access and edit-oriented workflows.
plan
Structured planning agent for outlining work before execution.
Delegated Agents
general
General-purpose agent for researching complex questions and executing multiple units of work in parallel.
explore
Exploration agent optimized for codebase discovery with read, grep, glob, bash, webfetch, and search access.
fast-explore
Faster read-only exploration profile limited to read, grep, glob, list, and tree.
planner
Planning-oriented agent for multi-step implementation strategies; produces step-by-step plans without modifying files.
scout
Read-only research agent for external libraries, dependency source, documentation, and public repositories. Can clone remote repos via repo_clone. Requires the NIKCLI_EXPERIMENTAL_SCOUT flag.
researcher
Read-only background research agent that collects evidence and returns source-backed findings; can delegate subtasks to fast-explore or planner.
code-reviewer
Reviews code for quality and safety using read, grep, glob, list, and bash.
ultrareview-reviewer
Specialized reviewer for a single domain within a parallel ultrareview fleet; hidden from the primary agent picker.
debugger
Debugging-oriented agent with read, search, shell, and edit access; identifies root cause and applies minimal fixes.
test-runner
Runs tests, analyzes failures, and proposes fixes using read, grep, list, bash, and edit.
refactor
Applies safe cleanups without intended behavior changes using read, grep, glob, bash, edit, and write.
delegator
Coordination agent that synthesizes results from background subagent runs; operates as an internal helper and is hidden from the primary agent picker.
Internal & support
support
Documentation and how-to assistant for nikcli features, commands, configuration, and
troubleshooting. Read-only: it does not edit the workspace. Invoked from the TUI support
dialog (/support, leader keybind), not from the primary agent picker.
Exposing support as a primary agent would let users start a session that cannot
apply edits. Keeping it behind the support dialog makes the read-only scope obvious.
Agent modes & permission overlays
The mode field on an agent controls where it can be invoked — it is
not the same as the permission mode shown in the TUI command palette. See
Permissions → Permission modes for the latter.
| Mode | Meaning |
|---|---|
primary | Available as a top-level agent for normal sessions. |
subagent | Available only for delegated work. |
all | Can be used as both a primary and delegated agent. |
hidden | Internal helpers such as compaction, title, summary, and support. |
Each agent starts from default permissions, applies its built-in overrides, and then merges
any user config overrides on top. The TUI Permission modes dialog
(require_approval / approve_for_me / full_access /
custom) writes this same config.agent.<name>.permission map,
so the override is visible in the agent config dump.
Customization
Agents can be added, disabled, or overridden in config.agent. Common fields
include model, prompt, description,
temperature, top_p, mode, steps,
hidden, and permission.