Linter Agent

The Linter 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 designed to be codebase-aware: when a warning is caused by interactions across modules, the agent can explore related files and suggest coordinated updates across the project.

Verilator is required

The Linter 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 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.