Verifrog – a Verilog/SystemVerilog testing framework an AI agent can drive

Verifrog, an open-source Verilog/SystemVerilog testing and debugging framework written in F#, has been released, enabling AI agents to drive RTL simulations through Verilator and Icarus Verilog via a Model Context Protocol (MCP) server. The framework provides type-safe signal access, checkpoint/restore, fork-based hypothesis testing, and signal forcing, allowing agents to pinpoint bugs such as an ALU SUB operation failure. It supports structured tests in F# that run under `dotnet test`, with features like VCD waveform analysis and comparison/sweep utilities.

An open-source Verilog/SystemVerilog testing and debugging framework in F . Drive your RTL through Verilator https://verilator.org and Icarus Verilog http://iverilog.icarus.com/ with type-safe, structured access to every signal, memory, and register — and let an AI agent debug it for you over MCP. Traditional Verilog testbenches are tedious and inexpressive; UVM is powerful but heavyweight. Verifrog gives you Verilator's speed with the ergonomics of a modern language — tests that read like specifications, checkpoint/restore and fork-based hypothesis testing, and an MCP server so an agent can open your design, step it, force signals, and pinpoint a bug on its own. Verifrog ships an MCP server, so an AI agent can drive your RTL simulation directly — opening a design, stepping cycles, reading and forcing signals, and checkpointing state to test hypotheses. In this demo, a failing test leads the agent to investigate, checkpoint, force signals, and pinpoint a bug in the ALU's SUB operation: verifrog-debugging-demo-2x.mp4 Write structured, readable tests in F that compile and run your RTL through Verilator. Read and write any signal, memory, or register by name. Assert values with clear failure messages. Run Verilator and Icarus Verilog tests side-by-side under a single dotnet test . Verifrog's simulation model is fully controllable from code — you can pause at any point, inspect every signal in the design, and step forward cycle-by-cycle. But the real power is in the tools built on top of this: - Checkpoint/Restore — Snapshot the entire simulation state every register, every memory cell and restore it later in microseconds. Hit a bug at cycle 50,000? Save a checkpoint before the failure, then repeatedly restore and probe different signals without re-running the simulation from scratch. - Fork — Explore a what-if scenario and automatically snap back. "What would happen if I forced this signal high?" Fork runs your experiment, captures the result, and restores the original state — so you can try multiple hypotheses from the same point without manual save/restore. - Compare and Sweep — Run two configurations side-by-side from the same state Compare , or sweep a parameter across many values Sweep . Both use checkpoints internally to ensure each scenario starts from identical state. - Signal forcing — Override any internal signal and hold it across clock cycles. Inject faults, disable clock gating, force a bus value — then release and watch the design recover. - Tracing and RunUntil — Record signal values over a window of cycles Trace , or advance the simulation until a condition is met RunUntil , RunUntilSignal . No more guessing how many cycles to step. - VCD waveform analysis — Parse simulation waveform dumps and query them programmatically: find when a signal first changed, count pulses, check timing relationships, verify FSM state coverage. Available as both a library Verifrog.Vcd for use in tests and a command-line tool verifrog-vcd for quick analysis. | Verifrog | Raw Verilator C++ | cocotb | UVM | | |---|---|---|---|---| Testbench language | F Expecto + declarative .verifrog | C++ | Python | SystemVerilog | Simulation engine | Verilator / Icarus | Verilator | any VPI simulator | any SV simulator | Checkpoint / restore | Built in state snapshot in µs | Hand-rolled | No | No | Fork / compare / sweep | Built in | Hand-rolled | No | Manual | Signal forcing | By name, held across cycles | Manual pointer writes | .value assignment | uvm hdl force | Named memory / register access | TOML-driven, by name | Manual | Manual | Config DB / RAL | AI agent debugging MCP | Built in | No | No | No | Learning curve | Low | Medium | Low | High | Verifrog leans on Verilator for raw speed, so it inherits Verilator's two-state limitation — for timing-accurate, four-state X/Z testbenches it can also drive Icarus Verilog under the same test suite. If you need cycle-accurate X-propagation as the default, a VPI-based flow like cocotb may fit better; if you want fast checkpoint/fork-driven debugging with an agent in the loop, that's where Verifrog is aimed. .NET 8+ SDK https://dotnet.microsoft.com/download Verilator 5+ https://verilator.org/guide/latest/install.html - clang++ macOS, included with Xcode or g++ Linux Icarus Verilog http://iverilog.icarus.com/ optional, for timing-accurate testbenches git clone https://github.com/bryancostanich/verifrog.git cd verifrog ./install.sh Symlinks verifrog to /usr/local/bin Or add bin/ to your PATH manually: export PATH="/path/to/verifrog/bin:$PATH" verifrog build samples/counter verifrog test samples/counter cd your-project verifrog init . Edit verifrog.toml with your design, then: verifrog build verifrog test See the full Getting Started Guide /bryancostanich/verifrog/blob/main/docs/getting-started.md for a step-by-step walkthrough. Most hardware tests are just "set signals, step, check." Write those declaratively in a .verifrog file — no F needed: test "counts to 10 when enabled" Smoke : write enable = 1 step 10 expect count == 10 test "load then count" Unit : write load value = 42, load en = 1 step 1 write load en = 0, enable = 1 step 5 expect count == 47 Or in F when you need more control: js open Verifrog.Sim open Verifrog.Runner let tests = testList "counter" test "counts to 10 when enabled" { use sim = SimFixture.create sim.Write "enable", 1L | ignore sim.Step 10 Expect.signal sim "count" 10L "count should reach 10" } Both run in the same test suite — same categories, same --report , same verifrog test . Save simulation state, run forward, restore, try something different — all in code: test "investigate overflow behavior" { use sim = SimFixture.create sim.Write "enable", 1L | ignore sim.Step 200 // Save state right before the interesting part let cp = sim.SaveCheckpoint "before overflow" // Run forward and observe sim.Step 60 let count = sim.ReadOrFail "count" let overflowed = sim.ReadOrFail "overflow" printfn "After 60 more cycles: count=%d overflow=%d" count overflowed // Restore and try a different approach sim.RestoreCheckpoint "before overflow" // What if we load a value near the limit? let result = sim.Fork fun s - s.Write "load en", 1L | ignore s.Write "load value", 250L | ignore s.Step 1 s.Write "load en", 0L | ignore s.Step 10 s.ReadOrFail "overflow" // sim is back to "before overflow" — Fork restored automatically // Sweep across multiple load values to find the boundary let results = sim.Sweep 248L; 249L; 250L; 251L; 252L , fun loadVal s - s.Write "load en", 1L | ignore s.Write "load value", loadVal | ignore s.Step 1 s.Write "load en", 0L | ignore s.Step 10 s.ReadOrFail "overflow" for loadVal, overflow in results do printfn " load=%d - overflow=%d" loadVal overflow } test "verify timing with VCD analysis" { use sim = SimFixture.create // ... run stimulus ... let vcd = VcdParser.parseAll "output/sim.vcd" // When did the FSM first enter state 5? let t = VcdParser.firstTimeAtValue vcd "fsm state" 5 // How many times did overflow pulse? let pulses = VcdParser.highPulseCount vcd "counter.overflow" // What states did the FSM visit? let states = VcdParser.uniqueValues vcd "fsm state" } Verifrog provides hardware-domain test categories so you can run the right tests at the right time: verifrog test --category Smoke Quick sanity — design is alive seconds verifrog test --category Unit Focused signal/block tests verifrog test --category Integration Multi-block data flow verifrog test --category Parametric Sweeps and value ranges verifrog test Everything Categories are lightweight testList wrappers — just group your tests: js open Verifrog.Runner.Category let tests = testList "MySoC" smoke test "comes out of reset" { ... } unit test "counter increments" { ... } golden test "matches reference output" { ... } Also available: stress long-running , golden reference outputs , regression bug-fix coverage . Your Test Project Expecto | v Verifrog.Runner — SimFixture, Iverilog backend, Expect helpers | v Verifrog.Sim — Sim type, Memory/Register accessors, TOML config | v libverifrog sim — Generic Verilator C++ wrapper built per-design | v Verilator — Your compiled RTL | Library | What it does | |---|---| Verifrog.Sim | Core simulation API: create, step, read/write signals, checkpoint/restore, force, fork/sweep, memory/register access | Verifrog.Runner | Test infrastructure: SimFixture lifecycle, Iverilog backend, Expect assertions, test categories Smoke/Unit/Parametric/Integration/Stress/Golden/Regression | Verifrog.Vcd | Standalone VCD waveform parser: parse files, query signals, value-at-time, transitions, timing analysis | Verifrog.Vcd.Cli | Command-line VCD analysis tool with text and JSON output | verifrog CLI | Build tool: init , build , clean , test , debug interactive REPL , debug-server JSON , mcp-server MCP for Claude | libverifrog sim | Design-agnostic C++ shim: signal discovery, direct-pointer access, checkpoint via memcpy | VS Code Extension | Syntax highlighting for .verifrog files, signals panel, checkpoints panel, debug toolbar experimental | All project configuration lives in verifrog.toml : design top = "my module" sources = "rtl/ .v" test output = "build" memories.data ram path = "u ram.mem" banks = 1 depth = 1024 width = 32 registers path = "u regfile.regs" width = 8 registers.map CTRL = 0x00 STATUS = 0x01 DATA = 0x02 See the full Configuration Reference /bryancostanich/verifrog/blob/main/docs/config-reference.md . | Sample | What it demonstrates | |---|---| | alu regfile /bryancostanich/verifrog/blob/main/samples/alu regfile sram /bryancostanich/verifrog/blob/main/samples/sram iverilog tb /bryancostanich/verifrog/blob/main/samples/iverilog tb dotnet test i2c bfm /bryancostanich/verifrog/blob/main/samples/i2c bfm Multiple ways to debug your simulations: Interactive REPL — the fastest path. Step the simulation, read/write signals, set checkpoints, force values, all from the command line: verifrog debug sim write enable 1 sim step 10 sim read count count = 10 sim checkpoint before overflow sim step 300 sim restore before overflow Back to cycle 10 instantly JSON debug server — for programmatic access. Reads JSON commands from stdin, writes JSON responses to stdout: echo '{"cmd":"read","signals": "count","enable" }' | verifrog debug-server MCP server — exposes simulation tools directly to Claude: verifrog mcp-server Speaks MCP protocol JSON-RPC 2.0 over stdio VS Code extension — syntax highlighting for .verifrog files, signals panel, test running. VS Code step-through debugging of F test code is experimental and has known limitations /bryancostanich/verifrog/blob/main/docs/debug-guide.md debugging-experimental . See the full Debug Guide /bryancostanich/verifrog/blob/main/docs/debug-guide.md for all options. | Guide | For | |---|---| | Core Concepts /bryancostanich/verifrog/blob/main/docs/concepts.md Debug Guide /bryancostanich/verifrog/blob/main/docs/debug-guide.md API Reference /bryancostanich/verifrog/blob/main/docs/api-reference.md VCD Parser Guide /bryancostanich/verifrog/blob/main/docs/vcd-guide.md VCD CLI Reference /bryancostanich/verifrog/blob/main/docs/vcd-cli.md CLI Reference /bryancostanich/verifrog/blob/main/docs/cli-reference.md verifrog init , build , clean , test , debug , results Configuration Reference /bryancostanich/verifrog/blob/main/docs/config-reference.md verifrog.toml section and key Declarative Tests /bryancostanich/verifrog/blob/main/docs/declarative-tests.md .verifrog files without F code Cookbook /bryancostanich/verifrog/blob/main/docs/cookbook.md CI Integration Guide /bryancostanich/verifrog/blob/main/docs/ci-guide.md Extension Guide /bryancostanich/verifrog/blob/main/docs/extension-guide.md Architecture /bryancostanich/verifrog/blob/main/docs/architecture.md Architecture Decisions /bryancostanich/verifrog/blob/main/docs/ARCHITECTURE DECISIONS.md Troubleshooting /bryancostanich/verifrog/blob/main/docs/troubleshooting.md Apache 2.0