Custom Agents

NEX supports Custom Agents, allowing you to define your own specialized assistants, such as a read-only RTL reviewer or a regression tracker, and launch them from the command line.

What is a Custom Agent?

A custom agent is a NEX agent specialized for your own workflow. You define what it is for and what it can use, and start it with nex --agent=<name> like any built-in agent. Each custom agent has:

• Instructions: What the agent does and how. NEX adds them on top of its built-in guidance, safety rules, approval policy and your NEX.md.
• Skills: Your custom skills and NEX's built-in default skills.
• Tool Reach: Whether the agent has a shell (and with it background jobs and skill scripts).
• Delegation: Which built-in sub-agents the agent may hand work to.
• MCP Servers: Which servers from your mcp.json are connected when the agent starts.

Creating an Agent

The easiest way to create an agent is to prompt NEX with the agent's specification: what the agent is for, how it should work, and which sub-agents or MCP servers it needs. NEX turns it into an agent file for you:

Create an agent called rtl-reviewer. It reviews Verilog and SystemVerilog code for inferred
latches, unsafe clock-domain crossings, reset problems and naming that breaks our conventions,
and reports each finding with the file, line and a suggested fix. It only reviews: it must not
run commands or edit the code.

NEX writes the agent to agents/rtl-reviewer.md in your project:

---
name: rtl-reviewer
description: "Reviews Verilog and SystemVerilog code for inferred latches, CDC, resets, and naming conventions."
shell: false
---

# RTL Reviewer Agent

You are the `rtl-reviewer` agent. Your sole purpose is to review Verilog and SystemVerilog code and report specific design issues.

## Review Criteria
You must analyze the provided codebase for the following issues:
1. **Inferred Latches**: Look for incomplete `if-else` or `case` statements in combinational `always` blocks (`always_comb` or `always @*`).
2. **Unsafe Clock-Domain Crossings (CDC)**: Identify signals crossing between asynchronous clock domains without proper synchronizers (e.g., 2-flop synchronizers, async FIFOs, handshakes).
3. **Reset Problems**: Check for synchronous vs. asynchronous reset mismatches, missing resets on sequential logic, reset domain crossings, and unsafe reset deassertion.
4. **Naming Conventions**: Check that the code adheres to standard RTL naming conventions (e.g., active-low signals ending in `_n` or `_b`, clock and reset signals clearly identifying their domains, consistent casing).

## Reporting Format
For each finding, provide a report using exactly the following format:
* **File:** `<filename>`
* **Line:** `<line number>`
* **Issue:** `<description of the issue>`
* **Suggested Fix:** `<concrete suggestion or code snippet to resolve the issue>`

## Constraints
* **DO NOT** run any shell commands.
* **DO NOT** use tools to edit or patch the code.
* Your role is strictly read-only analysis and reporting.

Because the agent must not run commands, NEX set shell: false (see Shell Access).

In an interactive session, when NEX finishes it confirms the new agent (Agents reloaded with its name), or warns you if the file it wrote cannot be loaded. You can then launch it.

To create an agent for all your projects, ask for a global agent. NEX writes it to ~/.nex/agents/. That folder is outside your workspace, so NEX needs your approval to write there and cannot do it with --approval-policy=auto.

Writing an Agent File

If you prefer to write or edit an agent yourself, this is how agent files work. An agent file starts with its options between two --- lines, followed by the agent's instructions.

File Placement

Like skills, agents can be scoped locally or globally:

• Workspace Agents: Place your file in ./agents/<name>.md within your project repository. This ensures the agent is tracked as project collateral and shared with your team.
• Global Agents: Place your file in ~/.nex/agents/<name>.md for personal agents you want available across all your projects.

Each agent is one .md file directly in the folder. The agent's name comes from its name option, not from the file name. Subfolders are ignored, and Markdown files without options (such as a README.md) are skipped.

The folders searched are set by the AGENTS_DIRECTORIES setting, a JSON list that defaults to ["./agents", "~/.nex/agents"]. For example, to add a team folder:

AGENTS_DIRECTORIES=["./agents", "~/.nex/agents", "/shared/nex/agents"]

Your list replaces the default, so keep the default folders in it if you still want them. Relative paths are resolved from the folder NEX is launched in, and folders listed first win over later ones.

Agent Options

subagents and mcp are lists, written in brackets or one item per line:

subagents: [general, verification]
mcp: [sqlite]

A single name without brackets (subagents: general) is reported as an error.

The instructions after the options must not be empty. Unknown options are ignored but reported (for example ignored keys: subagent), so a typo such as subagent: does not go unnoticed.

Shell Access

By default an agent has a shell, background jobs and skill scripts. With shell: false all three are removed; skills still load. File read and write, PDF reading and writing, and web search (when configured) are always available.

Delegation

A custom agent cannot delegate unless you list sub-agents, and then only the listed ones are available. Valid names are NEX's built-in sub-agents: general, lens, verification, specification, vivado, radiant, virtuoso and office_word. Any other name, such as fpga, is reported together with the list of valid names.

MCP Servers

Servers listed under mcp are connected before the first prompt and stay connected for the whole session. A custom agent has no tools to mount or unmount servers itself, and /mcp unmount leaves its servers in place. /mcp list shows them under "Pinned by agent". See MCP Servers for how to define servers.

mcp is only for your own servers in mcp.json. To use NEX's built-in tool integrations, such as Vivado, Radiant, Questa, VCS or Virtuoso, delegate to the sub-agent that provides them; see Delegation-Only Sub-Agents for which sub-agent connects to which server.

If a server is missing or fails to start, NEX prints a warning and the agent runs without it. Fix your mcp.json, then run /mcp mount <name> to connect it. The same command restarts a server that stops working during the session. You can still mount other servers by hand with /mcp mount.

Using Custom Agents

Launch a custom agent by name:

nex --agent=rtl-reviewer

Edits to an agent file apply the next time you launch it.

Managing Agents in Chat

Use /agents to see which custom agents NEX found:

/agents
/agents list
/agents reload

• /agents (or /agents list) lists each agent with its description and source folder. The running agent is marked (active), and files that could not be loaded are shown in red with the reason.
• /agents reload rescans the folders and prints which agents were added or removed. If the file of the running agent changed, NEX tells you to restart it with --agent=<name>.

Headless Mode

Custom agents also work in headless mode. The agent field of the JSON output carries the custom agent's name:

nex --agent=rtl-reviewer --prompt="Review rtl/fifo.sv" --json-output

To resume a session, pass the agent again; without --agent, the session continues under the default agent:

nex --agent=rtl-reviewer --session-id=<id> --prompt="Now review rtl/top.sv" --json-output

Limitations