FPGA Design with Logix Engine and Claude Code¶

In this tutorial, Claude Code designs hardware for you through Logix Engine. You describe what you want, such as "make the LED fade through the colors of the rainbow", and Claude writes the necessary source files, builds them, tests them, shows the waveforms and programs the board. You don't need to set up a toolchain, write Verilog yourself or even understand the Verilog language.

Tip

The prompts in this tutorial are in English, but you can write them in any language Claude understands, such as Spanish, German, Hebrew or Japanese.

Background¶

Logix Engine ("the engine" in short) is an open source MCP server that takes care of the FPGA design cycle: lint, build, test, simulate and program the board. It works with AI agents such as Claude Code, and with regular apps such as the Logix IDE. It downloads the open source FPGA tools it needs, and knows about boards, with their FPGAs and pins. Logix Engine is part of the Open Logix project.

What you need¶

An Apple Mac computer with Apple Silicon (M1 or later).
Claude Code, installed and signed in to your Claude account, so that claude starts it in a terminal. If it isn't installed yet, follow the official Claude Code installation instructions.
An FPGA board from the engine's catalog, and its USB cable. The examples use the iCESugar v1.5, which has an RGB LED and 4 switches. Any board in the catalog works: replace "iCESugar v1.5" with your board in the prompts, and Claude adapts the designs to it.

Note

Without a board, you can still do every step but 9.

Each text block is labeled with where it goes:

Terminal:

echo "a command"

Claude Code:

A prompt.

Type the prompts as they are, or in your own words or language.

1. Install the engine¶

Open the engine's Releases page, find the release marked Latest (not necessarily the newest one: newer pre-releases are development builds) and download its logix-engine-darwin-arm64-<date>.tgz to your Downloads folder.

Clear the download flag and unpack it:

Terminal:

cd ~/Downloads
xattr -c logix-engine-darwin-arm64-*.tgz
tar -xzf logix-engine-darwin-arm64-*.tgz

Important

The engine isn't signed with an Apple Developer ID yet. xattr -c tells macOS to allow it; without it, macOS refuses to run the engine.

Check that it runs:

Terminal:

~/Downloads/logix-engine/logix-engine --version

It prints the engine's version, a date such as 2026.11.09.

2. Connect Claude Code to the engine¶

Register the engine with Claude Code once, for every folder:

Terminal:

ENGINE=~/Downloads/logix-engine/logix-engine
ENGINE_HOME=~/.logix/claude-code/engine
claude mcp add -s user logix-engine -- $ENGINE --engine-folder $ENGINE_HOME
claude mcp list

The list shows logix-engine as connected. The engine keeps the FPGA tools it downloads, and its logs, in its engine folder, ~/.logix/claude-code/engine.

3. Create the project¶

Make a folder for the tutorial's project. You do this only once:

Terminal:

mkdir -p ~/logix-tutorial

4. Start Claude Code¶

Terminal:

cd ~/logix-tutorial
claude

Ask what the engine can do:

Claude Code:

What can Logix Engine do? Keep it short.

Claude lists the engine's tools: lint, build, test, simulate, program the board and more.

Important

The first time Claude uses one of the engine's tools, Claude Code asks for permission: choose "Yes, and don't ask again" for the logix-engine tools, so the rest of the tutorial flows. Claude also asks before it writes files in your folder.

Now tell the engine to fetch the open source FPGA tools it needs:

Claude Code:

Download the FPGA tools the engine needs, and show me the progress.

Note

The tools are downloaded into the engine folder you set in step 2, ~/.logix/claude-code/engine, and don't change your computer's setup. This takes a minute or two, only the first time.

5. Choose your board¶

Claude Code:

Which boards does the engine support? Group them by FPGA family, names only.

The engine knows about 80 boards: their FPGA, how to program them, and what's on their pins. Find yours, and ask about it:

Claude Code:

Tell me about the iCESugar v1.5: its FPGA, its clock, its LED and its switches.

Claude answers from the engine's board catalog: an iCE40 UltraPlus UP5K, a 12 MHz clock on pin 35, an RGB LED that's lit when its pins are low, and 4 switches, with their pins. It never has to guess a pin. To see how two boards differ:

Claude Code:

Compare the iCESugar v1.5 with the iCEBreaker.

6. Blink an LED¶

Claude Code:

Start a new project here for the iCESugar v1.5: blink the RGB LED in green about once a second. Then build it.

Claude writes three files and builds them:

main.v: the design, a counter whose top bit drives the LED's green pin.
pinout.pcf: which FPGA pins the design's signals use.
logix.json: Claude's notes on the project, such as its board.

The build ends with a bitstream in the _build/ folder in the project, and a short report: how much of the FPGA the design uses, and the fastest clock it could run at.

7. Test it¶

On an FPGA, you test before you program the board. Ask for a testbench, a simulation that checks what the design does:

Claude Code:

Write a testbench that checks the green LED turns on and off at the right times, using a small counter so the test is quick. Run it.

Claude writes main_tb.v, and the test passes. Now see a failure:

Claude Code:

Change the testbench to expect the LED to turn on one clock cycle too early. Run it, explain the failure, then put it back.

The engine reports the failed check at its line and simulation time, and Claude explains what went wrong.

8. See the signals¶

Claude Code:

Simulate the testbench and open the waveforms in GTKWave.

GTKWave opens with the clock, the counter and the LED. Zoom in to watch the counter count and the LED switch.

9. Program the board¶

Connect the board with its USB cable.

Claude Code:

Is my board connected?

Claude lists what's connected, and how well each device matches your board. Then:

Claude Code:

Program the board with the design.

The LED blinks green, about once a second: a design that went from a sentence to real hardware.

10. Change it with prompts¶

From here on, say what you want, and Claude changes the design in your project folder, tests it and programs the board. Try these one at a time, and watch the board after each:

Claude Code:

Change the design: make the LED step through its 8 colors (off, red, green, blue and their mixes), about 2 a second. Update the testbench, run it, then program the board.

Claude Code:

Use the 4 switches: switch 1 pauses the colors, and switches 2 to 4 set the speed. Test it and program the board.

Claude Code:

Make the LED fade smoothly through the colors of the rainbow, using PWM. Program the board.

Claude Code:

When switch 1 is on, make the LED breathe slowly on and off in blue, like a sleeping laptop, instead of the rainbow.

Bigger changes work too:

Claude Code:

Put the rainbow in its own module with a speed parameter, give it its own testbench, and keep main.v short. Run all the tests.

Tip

If the board does something you didn't expect, say what you see, such as "the LED is green when it should be red", and let Claude find out why.

11. Ask questions¶

Claude knows your design and the engine's reports, so ask about either:

Claude Code:

How much of the FPGA does the design use now? What uses the most?

Claude Code:

What's the fastest clock this design could run at, and what limits it?

Claude Code:

Explain main.v line by line, as if I'm new to Verilog.

Claude Code:

Make a diagram of the design and open it.

Claude Code:

Why did you choose that counter width? What would happen with a 20-bit counter?

12. When things go wrong¶

The engine reports problems as data, with their file and line, so Claude can fix them:

Claude Code:

Put a typo in main.v on purpose, build it, show me the error, then fix it.

Claude Code:

Check the design for warnings with the linter, and fix them.

Claude Code:

Format all the Verilog files.

Disconnect the board, then:

Claude Code:

Program the board with the design.

Claude reports that the board isn't connected, and what to check. Connect it again and ask again.

13. Keep going¶

Some ideas, each one prompt:

"Send 'hello' over the board's USB serial port once a second, and show me how to read it on my Mac."
"Make a reaction game: light the LED in a random color, and count how long until I flip switch 1."
"Turn the color sequence into a table at the top of main.v that I can edit."
"Make the design work on the iCEBreaker too." Then ask what changed.

Start each new design in its own folder, and run claude there.

Clean up¶

Build files: ask Claude to clean the build folder, or delete _build/.
To disconnect the engine from Claude Code: claude mcp remove --scope user logix-engine
To remove the engine, delete ~/Downloads/logix-engine and its engine folder, ~/.logix/claude-code/engine.

Learn more¶

Logix Engine: what it is and where it's going.
Tool API: every tool Claude used here, for writing your own frontend or agent.
Logix IDE: the same engine in an app, the Arduino experience, for FPGAs.
Logix Catalog: the boards, and how to add yours.

Logix Engine is free and open source, under MIT or Apache 2.0. To report a problem or share an idea, open an issue on GitHub.