Linter Task Agent

The Linter Task Agent runs a real RTL linter (Verilator) on your Verilog/SystemVerilog code, then proposes surgical, logic-preserving fixes for any issues it finds.

It is a focused task agent: it can be run directly by a user from the CLI in headless mode, or invoked by higher-level orchestrator agents when lint remediation is one step in a broader flow.

Verilator is required

The Linter Task Agent uses Verilator under the hood. Make sure verilator is installed and available on your PATH.

Key Features

Verilator-Backed Linting: Executes Verilator in --lint-only mode to surface real warnings and errors from your RTL.
Logic-Preserving Fixes: Suggests minimal changes intended to resolve lint findings without changing behavior.
Project-Aware Updates: Can identify when fixes require changes in multiple files (e.g., interfaces, parameters, or connected modules).
Readable Output: Prints a clear explanation of each fix and shows the updated RTL with syntax highlighting.
Automation-Friendly Mode: Optional JSON output makes it easy to integrate with scripts, CI pipelines, or editor tooling.

Command Options

Option	Shorthand	Description
`--input-file`	`-f`	Required. Path to the Verilog/SystemVerilog file to lint.
`--json-output`		Emits structured JSON output (status, files_to_update, fixed_code, fix_explanations).

Usage

Use the Linter task agent through the NEX CLI by specifying --agent=linter.

Basic Command

Run linting on a specific file and preview suggested fixes in the terminal:

nex --agent=linter --input-file=src/cpu/alu.sv

If the agent proposes updates, NEX prints an explanation and a suggested, updated version for each file that should change.

JSON Output (For Tooling)

For automation, CI pipelines, or editor integrations, you can request structured JSON output:

nex --agent=linter --input-file=src/cpu/alu.sv --json-output

What JSON output contains

The JSON payload includes the list of files to update, the corresponding revised code for each file, and human-readable explanations for the proposed fixes.

Configuration

You can customize the Linter's fix style and conventions to match your project by placing a NEX.md file in your project root. The agent reads this file and incorporates your instructions into its system prompt when generating fixes.

Common instructions include:

preferred formatting and naming conventions
how aggressive fixes should be (minimal vs. cleanup)
rules for handling warnings (auto-fix, suppress, or explicitly justify)

Tutorial

Step-by-step usage examples and guided walkthroughs are available in the GitHub tutorial repository.