Design a Simple PCB with Codex and KiCad: A Practical Guide

A small LED indicator board gives you a manageable first PCB: one power connector, one resistor, and one LED. Every connection is easy to trace, yet the project still takes you through the decisions that matter when turning a schematic into a board you can assemble.

Codex CLI can help turn those requirements into a design brief, check calculations, inspect saved project files, and run validation commands. You will build and review the schematic and layout in KiCad, keeping component selection, polarity, and physical fit visible at each step.

This guide follows a 5 V indicator from an empty KiCad project to a routed PCB, electrical and design rule checks, and inspected fabrication files. You can work locally or bring KiCad, Codex, and the project together on a Vagon Cloud Computer.

This documentation-based walkthrough has not been validated through an end-to-end KiCad run or a physical build. Use the checks below to verify your own project.

Define the LED Board Before Opening KiCad

Start with one purpose: illuminate a red LED when a correctly polarized, regulated 5 V supply is connected. The board will contain no regulator or reverse-polarity protection, so the input requirements belong in the design brief from the beginning.

Use the project name led-indicator and keep these requirements consistent throughout the schematic and layout:

The current path is J1 pin 1 → R1 → D1 anode → D1 cathode → J1 pin 2. This gives Codex a specific connection sequence to check later.

The WP7113ID datasheet lists a typical forward voltage of 1.9 V at 10 mA. Using that value, the estimate is I = (5 − 1.9) / 1000 = 3.1 mA. The LED’s forward voltage changes with current, so treat this as an approximation; actual current and brightness need checking on the assembled board.

For a conservative upper bound, use the highest specified supply voltage and the lowest resistor value. Even ignoring the LED’s voltage drop, 5.25 V / 990 Ω limits current to about 5.30 mA, with resistor dissipation below 28 mW. The selected 1 kΩ part from the Vishay MRS25 family provides ample power margin for this room-temperature example.

Give Codex the table and linked datasheets, then ask:

Review this LED indicator design before I draw the schematic. Check the current and resistor dissipation calculations, identify assumptions, and produce the expected component-to-component connections. Keep the three-component circuit and flag unresolved footprint or polarity details.

Resolve those details before placing symbols. In particular, J1 is unkeyed, so the finished board needs clear +5 V and GND labels.

Put KiCad, Codex, and the Project in One Workspace

Install KiCad 10 with its standard symbol and footprint libraries, then install Codex CLI using the official setup instructions. Run both on the computer that stores the project, so Codex can inspect the same files you open in KiCad.

On Vagon Cloud Computer, that computer can be a Windows desktop you access through your browser. KiCad, the terminal, datasheets, and validation outputs stay together while you switch between drawing, checking, and reviewing. Sign in to Codex with your own supported account; Vagon does not supply AI access. The steps below also work on a local Windows machine.

In KiCad’s Project Manager, choose File → New Project, name it led-indicator, and save it under a working folder such as C:\PCB. Keep the project in its own directory. You should have:

• led-indicator.kicad_pro: project settings.

• led-indicator.kicad_sch: the schematic.

• led-indicator.kicad_pcb: the board layout.

Save the agreed design requirements as design-brief.md alongside these files. Add a datasheets folder for the component PDFs and a reports folder for later checks.

Source: KiCad Documentation Contributors

Open PowerShell in C:\PCB\led-indicator and check the tools:

kicad-cli version
codex --version
codex

kicad-cli version
codex --version
codex

kicad-cli version
codex --version
codex

If PowerShell cannot find kicad-cli, locate kicad-cli.exe in your KiCad installation’s bin folder and invoke its full path, or add that folder to your terminal’s PATH. Record both tool versions in the project notes.

Start Codex with a bounded inspection request:

Read design-brief.md and list the KiCad project files in this directory. Report the installed KiCad CLI version and any missing inputs. Do not modify the project yet.

Check that its response names the correct directory. This establishes file and command access; schematic capture and layout will happen in KiCad’s editors.

Build the Schematic and Review the Current Path

Open led-indicator.kicad_sch from KiCad’s Project Manager. Use the Schematic Editor’s symbol placement and wiring tools to turn the agreed circuit into connected pins.

Press A to open the symbol chooser. Place a generic two-pin connector, such as Connector_Generic:Conn_01x02, plus Device:R and Device:LED. These symbols describe electrical connections; their physical footprints come next.

Check the reference designators and make them J1, R1, and D1. Set J1’s value to TSW-102-07-G-S, R1’s value to 1k, and D1’s value to WP7113ID. Add Manufacturer and MPN fields for each component; use MRS25000C1001FCT00 for R1 and record its ±1% tolerance. Include these fields when exporting the BOM.

Arrange J1 on the left, R1 above or beside D1, and the return connection below. Keep the default schematic grid while placing and wiring symbols. Rotate components where needed, but identify the LED’s anode and cathode from its symbol pin properties rather than assuming that screen position determines polarity. The bar in the diode symbol marks the cathode.

Press W to draw wires from the actual pin endpoints. Connect J1 pin 1 to R1, the other end of R1 to D1’s anode, and D1’s cathode to J1 pin 2. Place +5V and GND power symbols on the input and return wires. Add the local net label LED_A to the wire between R1 and D1’s anode.

Source: KiCad Documentation Contributors

Zoom in to check that wires meet pins and that each label’s attachment point touches its wire. A nearby line or label can look connected while remaining electrically separate. Keep this small circuit readable without unnecessary wire crossings.

Save the schematic before asking Codex to inspect it. In PowerShell, from the project directory, export a netlist for an explicit connection review:

kicad-cli sch export netlist --output reports/led-indicator.net led-indicator.kicad_sch

kicad-cli sch export netlist --output reports/led-indicator.net led-indicator.kicad_sch

kicad-cli sch export netlist --output reports/led-indicator.net led-indicator.kicad_sch

Confirm that the export succeeds, then give Codex this request:

Compare reports/led-indicator.net with design-brief.md and the saved schematic. List the component pins on +5V, LED_A, and GND. Check that R1 is in series with D1 and that D1’s cathode returns to J1 pin 2. Report mismatches without changing files.

The expected result is three nets: +5V joins J1.1 and one R1 pin; LED_A joins R1’s other pin and D1’s anode; GND joins D1’s cathode and J1.2. Resolve discrepancies in KiCad, save, and regenerate the netlist before continuing.

Match Real Parts to Footprints and Resolve ERC Findings

Open KiCad’s Assign Footprints tool from the Schematic Editor toolbar. Select each component and preview its candidate footprint before assigning it. A matching pad count helps narrow the list, but the package dimensions and pin numbering determine whether the part will fit and connect correctly.

Source: KiCad Documentation Contributors

For this board, check three things:

• D1: Assign LED_THT:LED_D5.0mm: 2.54 mm pad spacing and 0.9 mm drills in the KiCad 10.0.0 library source. For Device:LED, pin 1 is the cathode and pin 2 is the anode. Match the physical LED’s cathode marking to pad 1.

• R1: Assign Resistor_THT:R_Axial_DIN0207_L6.3mm_D2.5mm_P10.16mm_Horizontal: 10.16 mm mounting pitch and 0.8 mm drills. The MRS25 body can reach 6.5 × 2.5 mm; check it against the actual courtyard and neighboring parts, since the footprint name describes a nominal 6.3 mm body.

• J1: Assign Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical: 2.54 mm pitch and 1.0 mm drills. The Samtec header has 0.635 mm square posts, about 0.90 mm across their diagonal. Confirm finished-hole tolerance and insertion allowance with your fabricator before ordering.

These dimensions were checked in the KiCad 10.0.0 library sources; compare them with your installed library. Preserve this mapping: J1 pad 1 → R1 pad 1 on +5V; R1 pad 2 → D1 pad 2 on LED_A; D1 pad 1 → J1 pad 2 on GND. Resistor polarity is interchangeable, but using fixed pad numbers makes the example easier to audit. Recheck dimensions and mapping for substitute parts.

Save the assignments and run KiCad’s Electrical Rules Checker. Select each finding to locate it in the schematic. Fix disconnected pins, incorrect labels, or other connection mistakes at their source.

Source: KiCad Documentation Contributors

Because J1’s pins are passive, ERC may report that the +5V and GND power-input symbols are not driven. For this externally supplied circuit, place power:PWR_FLAG on each supplied net that produces that finding. The flag tells ERC where power enters; it neither adds a physical component nor verifies the external supply.

Ask Codex for a focused review:

Read the saved schematic and the referenced footprint library files. Return a J1/R1/D1 checklist with pin-to-pad mapping, pad spacing, drill sizes, and datasheet discrepancies. Separately explain remaining ERC findings. Leave files and rule settings unchanged.

Rerun ERC after corrections and save its report under reports. Proceed when connection findings are resolved and any justified exception is documented.

Transfer the Schematic and Route the Board

Save the schematic, then open led-indicator.kicad_pcb from the Project Manager. Choose Tools → Update PCB from Schematic, or press F8. Review the proposed changes: the board should receive J1, R1, D1, their assigned footprints, and the three circuit nets. Apply the update and place the footprints on the canvas.

Source: KiCad Documentation Contributors

The netlist exported earlier was for inspection. KiCad’s normal schematic-to-PCB transfer uses this update tool directly. Repeat it whenever you change the schematic so the layout follows the saved circuit.

Before routing, open File → Board Setup. Keep two copper layers. Set the Default net class’s track width to 0.4 mm and clearance to 0.25 mm, with a 0.5 mm minimum copper-to-edge clearance under Constraints. These are generous choices for this low-current example, subject to your fabricator’s requirements. Also check its hole, annular-ring, solder-mask, and silkscreen limits; track spacing alone does not define a complete manufacturing ruleset.

Source: KiCad Documentation Contributors

Select Edge.Cuts and draw one closed rectangle. Set its corner coordinates in the rectangle’s properties so its width is exactly 25 mm and its height is 20 mm. Keep the outline free of gaps, duplicate segments, and intersections.

Place all three components on the front side. Position J1 near an edge with enough room for its mating connector. Put D1 where its light will remain visible, then arrange R1 between the input and LED anode. Keep component courtyards clear of each other and leave room to reach the solder joints from underneath.

Use the thin ratsnest lines to assess the arrangement before drawing copper. If the connections cross unnecessarily, rotate or move a footprint now. Placement is easier to correct before tracks occupy the available space.

Select use netclass width in the track-width control, then select F.Cu, press X, and route pad to pad. Inspect a completed segment’s properties to confirm 0.4 mm. The net class value is a routing default, not an enforced DRC minimum; a different width may pass DRC if it satisfies the configured constraints. Complete +5V from J1 to R1, LED_A from R1 to D1’s anode, and GND from D1’s cathode back to J1. This small circuit can usually be arranged without vias. Follow the PCB Editor’s routing and clearance controls rather than forcing a track through a collision.

Source: KiCad Documentation Contributors

A ground zone is optional. If you add one on B.Cu, assign it to GND, retain suitable thermal reliefs for hand soldering, and press B to fill it. Refill after later geometry changes and save the board so subsequent checks and exports use the reviewed copper.

Move reference labels away from pads and add readable +5V, GND, and LED polarity markings on F.Silkscreen. Save, then ask Codex:

Inspect the saved PCB against design-brief.md. Report its outline dimensions, component references, pad-to-net assignments, and track widths. Compare actual widths with the 0.4 mm routing choice and list discrepancies without modifying the layout.

Compare its findings with KiCad. An unrouted count of zero is the point to begin formal board validation.

Validate the Saved Board with DRC and Targeted Inspection

Save both editors before running checks. If you changed the circuit, update the PCB from the schematic again. Refill any zones, save the board, and keep the project files together so the checks can compare the intended schematic with its corresponding layout.

Use the KiCad CLI’s ERC and DRC commands to create repeatable reports from the project directory. Run each command and capture its exit code immediately afterward:

kicad-cli sch erc --format json --severity-all --exit-code-violations --output reports/erc.json led-indicator.kicad_sch
$ercExit = $LASTEXITCODE

kicad-cli pcb drc --schematic-parity --format json --severity-all --exit-code-violations --output reports/drc.json led-indicator.kicad_pcb
$drcExit = $LASTEXITCODE

"ERC exit: $ercExit; DRC exit: $drcExit"

kicad-cli sch erc --format json --severity-all --exit-code-violations --output reports/erc.json led-indicator.kicad_sch
$ercExit = $LASTEXITCODE

kicad-cli pcb drc --schematic-parity --format json --severity-all --exit-code-violations --output reports/drc.json led-indicator.kicad_pcb
$drcExit = $LASTEXITCODE

"ERC exit: $ercExit; DRC exit: $drcExit"

kicad-cli sch erc --format json --severity-all --exit-code-violations --output reports/erc.json led-indicator.kicad_sch
$ercExit = $LASTEXITCODE

kicad-cli pcb drc --schematic-parity --format json --severity-all --exit-code-violations --output reports/drc.json led-indicator.kicad_pcb
$drcExit = $LASTEXITCODE

"ERC exit: $ercExit; DRC exit: $drcExit"

With --exit-code-violations, 0 means no reported violations and 5 means findings were detected. Other nonzero codes indicate an execution problem that needs investigation. Confirm both commands completed and produced fresh reports before interpreting their contents. An old JSON file does not establish that the latest check succeeded.

The --severity-all option includes excluded findings for visibility. Review those separately from unresolved errors and warnings; their presence should have a documented reason. This sequence checks the copper already saved on disk, so the earlier refill-and-save step matters.

Ask Codex to turn the reports into a correction list:

Read the newly generated ERC and DRC reports. Group findings by severity and exclusion status. For each unresolved item, identify the affected references, nets, or coordinates and suggest a correction. Include schematic-parity findings. Do not change project files, suppress findings, or treat an execution failure as a passed check.

Use the reported locations to inspect problems in KiCad. A parity mismatch may require another schematic update; a clearance violation may require moving a track or component. Correct the underlying issue, save, and rerun both checks.

Before exporting, inspect the saved result through three complementary views:

Close and reopen the board from its project to confirm the reviewed layout was saved. Open View → 3D Viewer to check component orientation and obvious clashes, then compare critical dimensions with the datasheets. A missing or approximate model requires a dimensional check rather than an assumption of fit.

Source: KiCad Documentation Contributors

Record the tool version, check results, and remaining exceptions in the project notes. These checks establish the state of the design files; powered behavior requires the physical bring-up below.

Inspect Gerbers and Package One Consistent Revision

Create a new release folder, such as release/rev-a, after completing the design checks. Use a fresh directory for each revision so outdated files cannot remain mixed with new exports.

In the PCB Editor, open File → Plot and choose Gerber output. Set the destination to release/rev-a/fabrication. For this two-layer board, include F.Cu, B.Cu, F.Mask, B.Mask, F.Silkscreen, and Edge.Cuts. Include back silkscreen if you used it. Paste layers are unnecessary for this through-hole, hand-assembled example unless your manufacturing process specifically requires them.

Source: KiCad Documentation Contributors

Plot the selected layers, then use Generate Drill Files to export Excellon drill data into the same fabrication folder. Keep the Gerber and drill coordinate origins consistent.

Open the exported files in KiCad’s Gerber Viewer. Load the copper, mask, silkscreen, outline, and drill files together, then toggle their visibility. Confirm that:

• The outline measures 25 × 20 mm and surrounds the intended board.

• Drill holes align with the component pads on both copper layers.

• Mask openings expose the intended solder pads.

• Reference and polarity markings remain readable and clear of exposed pads.

Inspect these actual manufacturing files even if the 3D board preview looked correct. If you change the source board, rerun validation and regenerate the affected outputs before repeating this inspection.

Source: KiCad Documentation Contributors

From the Schematic Editor, export a BOM through Tools → Generate Bill of Materials. Check that J1, R1, and D1 each appear once with sufficient purchasing information, including the resistor’s value, tolerance, and selected part details.

Keep the fabrication folder separate from the project archive. The archive should retain the native KiCad files, any project-specific libraries, BOM, datasheets, design brief, and latest reports. Add a short release note with the revision, KiCad version, checks performed, and exceptions.

Ask Codex to inventory that package and identify missing or inconsistent files. Review its findings, then create the fabrication ZIP from the inspected folder for the manufacturer’s upload requirements.

Plan the First Power-On Before Ordering

Write the bring-up checklist while the circuit is still familiar. After assembly, inspect solder joints and LED orientation with power disconnected. Check for a short between J1’s +5 V and GND pins before connecting a supply.

For this board, set a bench supply to 5 V with a 10 mA current limit, verifying its output polarity before connection. Enable the output and confirm that the LED lights without the supply entering current limit. If it reaches the limit, switch off and investigate.

Measure the voltage across R1 with the meter in voltage mode. Divide that reading by R1’s resistance to estimate LED current: 3 V across 1 kΩ means 3 mA. Never place a meter in current mode directly across the supply.

Record the measured input voltage, resistor voltage, and LED behavior against the released revision. Keep these observations with the project before making your next design change.

FAQs

Can Codex design the entire PCB automatically?

This walkthrough uses Codex for planning, calculations, file inspection, and validation commands. You create and inspect the circuit in KiCad. Greater automation requires a separate, verified integration and still needs review of the resulting design.

Do I need an MCP server to follow this guide?

No. Codex can work with the saved project and installed KiCad CLI. MCP becomes relevant if you want additional design operations exposed through a compatible connector; it is not required for the workflow here.

Does passing DRC mean the board will work?

DRC checks the layout against configured rules. It cannot establish that your component choices, circuit behavior, or assembly are correct. Keep the datasheet checks and physical bring-up measurements in the process.

Do I need a cloud computer or powerful GPU?

A simple indicator board can be designed locally. Vagon is useful when you want KiCad, Codex, and project files on a remotely accessible desktop. GPU performance is not the reason to choose it for this circuit.