# Agents

Agents are defined in packages/nikcli/src/agent/agent.ts and configured through nikcli config overlays.

## Primary Agents

Primary

### ralph

Conversational primary agent intended for lighter interactive work.

Primary

### build

Default coding agent with the broadest tool access and edit-oriented workflows.

Primary

### 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

Hidden · read-only

### 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.

Why support is hidden

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](/docs/permissions#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`. |

Permission merging

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`.

## Related

-   [Tools Tool registry and per-agent tool gating.](/docs/tools)
-   [Permissions How permission rules merge with agent defaults.](/docs/permissions)
-   [Configuration config.agent overlays and model selection.](/docs/configuration)

---

Source: https://nikcli-ai.dev/docs/agents