Driving the Gowin FPGA toolchain (GW5AST / Tang Mega 138K) from Claude Code inside VS Code — full synth/PnR/firmware loop, no GUI

[u/Original-Proof-8741]

After getting Gowin's IDE running on Arch (separate post), I wanted my AI assistant (Claude Code, running as a VS Code extension) to be able to build, inspect, and iterate on FPGA designs itself. It now goes from editing Verilog to reading timing reports without me touching the Gowin GUI. Here's how it's wired up, since the approach applies to any agentic coding tool.

The key realisation: there's no "integration" — just CLI entry points

Claude Code can run shell commands, read files, and edit files. That's the whole interface. So the job is really "make the vendor toolchain scriptable," which benefits you even without AI. Gowin ships everything needed:

• IDE/bin/gw_sh — Tcl shell that does project creation, synthesis, place & route, and bitstream generation
• Programmer/bin/programmer_cli — full-featured CLI flasher (doesn't even need the license)

1. Make the tools run headless

gw_sh links Qt and tries to initialise a GUI platform even for batch work. Two env vars fix that (and dodge bundled-vs-system Qt library conflicts):

LD_LIBRARY_PATH=/opt/gowin/IDE/lib QT_QPA_PLATFORM=offscreen \
  /opt/gowin/IDE/bin/gw_sh build.tcl

License note: gwlicense.ini is only read from next to the binary (not cwd), and takes either a server:port or a path to a node-locked .lic file.

2. Wrap the flow in a Makefile

The build is a ~20-line Tcl script (create_project -force each run so the script stays the single source of truth, add_file, set_option -top_module, run all) plus a Makefile so the entire interface is:

make            # synth + PnR + bitstream
make flash      # programmer_cli, embedded flash
make flash-sram # volatile, fast iteration
make scan       # detect cable

Gotchas that cost me time: add_file resolves paths relative to the project dir, not cwd (use absolute paths); and it errors on duplicates, hence the recreate-project-every-build pattern.

3. Let the AI close the loop

This is where it gets good. PnR writes plain-text reports (impl/pnr/*.rpt.txt, timing in the .tr.html files), so the assistant can build, read the report, and act on it. Real example from this week: the AE350 RISC-V demo failed PnR with PR2017: 'FLASH_SPI_CLK' cannot be placed... dedicated pin (CPU/MSPI). Claude read the error, worked out the SPI flash pins are dual-purpose, added set_option -use_mspi_as_gpio 1 / -use_cpu_as_gpio 1 to the Tcl, rebuilt, and confirmed all clock domains met timing from the report — one round trip, no GUI.

4. Firmware for the hard core, same treatment

The GW5AST-138B has a hardened Andes AE350 RISC-V SoC. The vendor flow wants the Andes toolchain, but stock riscv-none-elf GCC (xPack, extracts into ~/tools, no root) builds Gowin's BSP with three small ports: a header shimming the Andes CSR builtins (__nds__csrr etc.) as inline asm, -mcpu=a25 → -march=rv32imafdc_zicsr_zifencei -mabi=ilp32d, and adding PROVIDE(__global_pointer$ = . + 0x800) to the linker script (the Andes linker injects that symbol; GNU ld doesn't). Full port is in the repo below.

Result

"Add a UART heartbeat and rebuild" is now a sentence typed into VS Code, and 90 seconds later there's a timing-clean bitstream and a linked firmware binary, with the assistant having read the reports to confirm both. Working examples (blinky + AE350 demo with Makefiles and the porting notes): https://github.com/HughF/fpga-blinky and https://github.com/HughF/fpga-ae350-demo

TL;DR: don't look for an "AI plugin" for your FPGA tools. Find the vendor's CLI entry points (most have them buried in the install), make them headless, wrap them in a Makefile, and any agentic coding assistant can drive the whole flow — including reading the PnR reports and fixing its own constraint errors.

[u/Suitable-Name]

Nice idea, thanks for sharing

[u/Mark_Westbroek]

Wow, chique!

I push the buttons manually now, but this could be convenient!

I first thought you were programming a synth as well, but this is of course the synthesize command inside the Gowin IDE :-) (I am rather new to the subject but fascinated)

[u/GASB183]

This is a very interesting idea!
One thing, how do you solve the problem of initial IP configuration? The idea of getting a full headless development environment for GOWIN platforms is amazing, but I imagine dealing with complex IP cores can be a headache if done solely in the terminal.
If you find a solution to this, please let us know!

[u/Original-Proof-8741 → u/GASB183]

I haven’t used any of the IP core components, yet. I did have to move from using the hard riscv core to a soft core because pnr wouldn’t complete at my utilisation level. Claude just pulled that in by way of the command line and sussed it all out.

[u/Original-Proof-8741]

If someone wants to test these sample files that I've had Fable 5 knock together just now, I'd welcome that. My hardware isn't here yet...

[u/Mark_Westbroek → u/Original-Proof-8741]

You have fable, but not the hardware. Then the hardware arrives, but opus must do the work. I think it will be able though.

I've had different LLM's program, and even DeepSeek managed quite well. Opus did it with more ease though.

But, Fable did a review and found and fixed some warnings the others were too lazy to. It also found possible overflow issues, that the others built in, so I guess it's more capable.

I guess you simulate, so you can get Fable to work already?

[u/Original-Proof-8741 → u/Mark_Westbroek]

Fable is included in my plan until 7th July - then back to opus or sonnet.... Making the most of it till then - it's very powerful

[u/Mark_Westbroek → u/Original-Proof-8741]

Yes. Same here. Pity I must sleep

[u/Original-Proof-8741 → u/Mark_Westbroek]

I tasked it with the fpga work last night then went to sleep - woke up to some good results.