A fast Rust-accelerated A* autorouter for KiCad PCB files. Compatible with KiCad 9 and KiCad 10. Available as both a KiCad Plugin with full GUI and a Command-Line Interface for scripting and automation.
π Project metrics β installs, downloads and traffic, updated daily.
Free and MIT-licensed. Donations cover the ~$500/month of cloud compute and AI development behind it.
Also via GitHub Sponsors or PayPal β see Support.
- Support β donate via Ko-fi, GitHub Sponsors or PayPal
- Features
- Quick Start
- KiCad Plugin β GUI, the Auto tab (the Autorouter, AI routing and placement, labels), installation
- Command-Line Interface β routing, planes, verification
- Documentation β full guide for every feature
- Project Structure & Module Overview
- Performance
- Command Reference β options per tool (full list:
--help/ configuration.md) - Project metrics β installs, downloads and traffic
- Requirements Β· Limitations Β· Contributing Β· License
KiCadRoutingTools is free and MIT-licensed, and it stays that way β there is no paid tier, no feature held back, and nothing in this repository is paywalled.
Donations go to what it costs to build and maintain it: about $500/month of cloud computing and AI-assisted development.
The compute is not incidental. Every change to the router is A/B-tested by replaying a corpus of real open-source boards on rented cores and grading each one for DRC violations and unconnected nets, and the ~770-file test suite fans out the same way. It is what stops a change that helps one board from quietly breaking ten others.
- β Donate on Ko-fi β card or PayPal, no account needed.
- GitHub Sponsors β one-time or monthly, billed with any other projects you sponsor.
- Prefer PayPal directly? paypal.me/DrAndyHaas (the sender needs a PayPal account).
A donation buys no priority support and unlocks no features. If you would rather contribute something worth more than money, route one of your own boards and file an issue for whatever breaks β see Contributing.
Fast, grid-based A* routing with a native Rust core (~10Γ faster than pure Python): octilinear (H/V/45Β°) multi-layer routing with automatic vias, and batch routing with incremental obstacle caching. Highlights below link to the full deep-dive docs.
Core routing
- Rust-accelerated A* pathfinding, multi-layer with automatic via insertion
- Rip-up and reroute β progressive N+1 blocker analysis, ripped-corridor avoidance
- Net ordering strategies β MPS (crossing-aware), inside-out, original, or bus-first, with MPS layer swaps
- Stub layer switching, vertical track alignment, turn-cost straightening
- Board-edge (Edge.Cuts arcs/cutouts), keep-out rule areas, and auto BGA exclusion zones β see Configuration
- Direction-aware stub / BGA / track proximity penalties
Differential pairs β see Differential Pairs
- Pose-based A* with a Dubins heuristic and adaptive setback angles for orientation-aware centerlines
- Bare-pad, multi-point (3+ terminals), and hybrid (coupled middle + single-ended legs) routing
- Automatic polarity resolution (opt-in pad swaps), U-turn prevention, GND return-via placement
- Electrically-short legs auto-defer to single-ended; per-layer impedance-controlled widths
Power & planes β see Plane Routing and Power Nets
- Wider power-net routing with automatic neck-down at fine-pitch pads
- Plane pours (pads are welded by the route step, #562) and plane layers several nets share (split round spines routed on the layer) with resistance / max-current reporting
- Disconnected-plane-region repair (region joins + pad taps) and GND return-via placement
Signal integrity
- Length matching β trombone meanders, auto DQ/DQS grouping, via-barrel aware
- Time matching β propagation delay, microstrip vs stripline
- Bus routing, plus guide corridors and keep-out zones drawn on a User layer
Placement, fanout & optimization
- Placement by function: parts sorted into functional groups, one objective annealed (
place_simple.py) over 12 seeds (6 started scattered, 6 with each group gathered), and a fast route (route.py --quick 2) of the 6 the objective rates best to keep the best (/plan-pcb-placement) - The design brief β state what the board is FOR, in a sibling the toolchain reads: which connectors are user-facing, which edge each belongs on and where along it
- Parts under other parts β part heights read off the 3D models, so a low part may stand under a module or shield can where it fits; a card in its socket (M.2) or a module on a stacking connector is declared in the brief and moves with its connector, admitting only parts known to fit under it
- Floorplan intent, graded β declare where parts belong and check the board against it, so "the render looks fine" stops being a verdict
- BGA / QFN fanout with decoupling-cap placement cleanup, Hungarian target-swap, and schematic sync
Cleanup & verification β see Utilities
- Post-route copper cleanup reconciled against the connectivity model (no orphaned or ripped-and-not-restored copper), with gap-snap connectors
- KiCad-oracle reconnect β routes the exact links KiCad's own DRC reports as unconnected
- Checkers for DRC, connectivity, orphan stubs, copper hygiene (
check_weird.py), and pad geometry
Interfaces
- Full KiCad plugin GUI (KiCad 9 & 10) and a scriptable CLI
- AI assistance β an Auto tab that runs the Autorouter, plans an entire routing workflow or places a board by function, per-field "Ask AI" helpers, and datasheet-driven power / high-speed / diff-pair analysis
- Board rendering β fast geometry PNG renderer (
route_render.py), placement stills (render_placement.py), a board's power components (render_power.py), and movies of a routing run (route_movie.py, made for every stress run) and of a placement, or the placement skill's whole flow through to the full route (place_movie.py) - Routing plans as files β save/load a whole routing chain as JSON: build one from a recorded command chain (
make_plan.py), run it headless through the real plugin (run_plan.py), or load it in the GUI
# Clone with git
git clone https://github.com/drandyhaas/KiCadRoutingTools.git
cd KiCadRoutingToolsOr download the ZIP and extract it.
Commands here use python3. On Windows, use py -3 (or python) if python3 is not found.
Install dependencies into the interpreter that will run the CLI:
python3 -m pip install -r requirements.txtThe KiCad plugin uses KiCad's Python. See Requirements for details.
python3 build_router.pyBy default this downloads a prebuilt binary for your OS from the project's GitHub Releases β no Rust toolchain required. Prebuilts are published for:
- Linux x86_64
- macOS arm64 (Apple Silicon)
- macOS x86_64 (Intel)
- Windows x86_64
If a prebuilt isn't available for your platform (e.g. Linux arm64) or the download fails, the script falls back to building locally with cargo.
If you'd rather build locally β or you're on a platform without a prebuilt β install Rust from rustup.rs:
# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Windows: Download and run rustup-init.exe from https://rustup.rs/After installation, restart your terminal or run source ~/.cargo/env, then:
python3 build_router.py --from-source # build locally instead of downloading
python3 build_router.py --tag v0.15.0 # download a specific release
python3 build_router.py --clean # remove all build artifactsTo route a whole board automatically, use one of two ways -- and an AI assistant asked to route a board with this package should do the same:
python3 py_router/autoroute.py board.kicad_pcb routed.kicad_pcb(Option C): no agent; it plans the chain from the board's own rules, footprints and nets and runs it. The plugin's Auto βΊ Autorouter tab runs the same script.- the
/plan-pcb-routingskill (Option B): an agent analyzes the board, plans the chain step by step with you, and runs it.
Option A: KiCad Plugin (Recommended for interactive use)
# Install the plugin
python3 install_plugin.py
# Then in KiCad: Tools β External Plugins β KiCadRoutingToolsOption B: Claude Code (AI-assisted routing)
Use Claude Code to analyze your PCB and generate a routing plan:
> /plan-pcb-routing kicad_files/my_board.kicad_pcb
Claude will:
- Analyze your board structure and identify components needing fanout (BGA/QFN/PGA)
- Detect differential pairs and DDR signals requiring length matching
- Identify power/ground nets and recommend plane vs trace routing
- Assess signal speeds and recommend GND return via placement
- Generate a step-by-step routing plan with explanations
- Run the commands and verify results
Other useful skills:
> /find-high-speed-nets kicad_files/my_board.kicad_pcb # Identify high-speed nets via datasheet lookup
> /analyze-power-nets kicad_files/my_board.kicad_pcb # Identify power nets and track widths
> /identify-diff-pairs kicad_files/my_board.kicad_pcb # Find diff pairs by pin function, recommend gap/impedance
> /recommend-stackup kicad_files/my_board.kicad_pcb # Stackup advice for impedance/time-matching accuracy
> /recommend-plane-mappings kicad_files/my_board.kicad_pcb # Which nets get planes, on which layers
> /diagnose-routing-failures my_board.kicad_pcb /tmp/route_output.txt # Root-cause failed routes, get a retry command
> /review-routed-board my_board_routed.kicad_pcb # Post-route QA: DRC, connectivity, length match, GND vias
> /plan-pcb-placement full kicad_files/my_board.kicad_pcb # Group, place 12 seeds, fast-route the 6 cheapest, keep the best, route end to end
See Claude Skills for what each skill does and how they fit together.
All of these are also available inside KiCad without leaving the plugin - see AI assistance in the plugin below. The plugin can run the analysis and routing skills through opencode instead of Claude Code (issue #503) - a Backend dropdown on the Auto tab selects the agent CLI, and opencode's provider/model strings open the door to other model providers. The placement runs need Claude Code, because they write files and opencode's analysis agent may not. The skills' output contracts are tuned on Claude models; smaller models may follow them less reliably.
Option C: Command Line -- route a whole board with autoroute.py
# Route the whole board: planes, fanouts, decap clearance, diff pairs and route
# passes, chosen from the board's own rules, footprints and nets
python3 py_router/autoroute.py my_board.kicad_pcb routed.kicad_pcb
# See its plan first, without running anything
python3 py_router/autoroute.py my_board.kicad_pcb routed.kicad_pcb --dry-runEvery step it ran, with its log and board, is in routed.kicad_pcb.autoroute/
(plan.json there records the chain and each pass's grade), and its last line,
AUTOROUTE_SUMMARY, names the shipped step with its open nets and DRC. See
autoroute.py. The
plugin's Auto βΊ Autorouter tab runs the same script on the open board.
Option D: A hand-built chain (the manual / expert path)
When a board needs steps autoroute.py does not take -- impedance control, length
matching, keep-away rules, buses, a particular plane map, or a net class that is a
real requirement rather than aspirational -- run the tools yourself, the kind of chain
/plan-pcb-routing plans:
If the parts need placement, place them first by their functional groups (see the
placement guide) and use the placed board as
my_board.kicad_pcb in this chain:
python3 py_placer/place_simple.py unplaced.kicad_pcb my_board.kicad_pcb --groups groups.json --intent intent.json# Pour the planes FIRST (#562): the fanout's plane-drop vias then land on
# real fill, and the route step welds plane pads into it.
python3 py_router/route_planes.py my_board.kicad_pcb poured.kicad_pcb --nets GND --plane-layers B.Cu
# Fan out a BGA, then tidy decoupling caps off the new vias (issue #130)
python3 py_router/bga_fanout.py poured.kicad_pcb -c U1 -o fanned.kicad_pcb --clearance 0.1
python3 py_placer/place_fanout_clearance.py fanned.kicad_pcb capclean.kicad_pcb --clearance 0.1
# Route differential pairs (the output is positional: route_diff's -o is --ordering)
python3 py_router/route_diff.py capclean.kicad_pcb diffed.kicad_pcb --nets "*lvds*"
# Route ALL remaining nets, plane nets included (their widths via --power-nets).
# This step ends with the in-run plane finalize that completes the planes.
python3 py_router/route.py diffed.kicad_pcb routed.kicad_pcb --nets "*" \
--power-nets GND --power-nets-widths 0.3The plugin provides a full graphical interface for all routing features, running directly within KiCad 9 or 10.
With Claude Code or opencode installed, the routing dialog gains AI assistance throughout (the plugin spawns the selected agent CLI headless, streams a live transcript, and fills GUI controls from the results). The Backend dropdown on the Auto tab picks the CLI: Claude Code runs Anthropic models; opencode takes provider/model strings for many providers (including its built-in free tier), with opencode auth login adding provider accounts. Both discover the same .claude/skills/; opencode runs them under a read-only pcb-analysis agent defined in opencode.json (the equivalent of the Claude run's read-only tool allowlist). Neither grants a dedicated write tool, though both grant Bash, so neither is a sandbox β the allowlist states intent, and --allowedTools auto-approves rather than restricts. Both can dispatch a subagent, so an analysis skill can hand its close-out to an independent verifier (#552): the Claude allowlist grants the dispatch tool per run, and the pcb-analysis agent grants opencode's task tool in opencode.json. A caller asking opencode for a tool set naming Write/Edit is refused rather than silently downgraded.
The tab has two sub-tabs:
- Routing - Plan Routing runs
/plan-pcb-routing: the plan fills the parameter fields across the tabs and appears as a checkable step list, which Run Selected Steps executes sequentially in-process on the live board with per-step status marks. Review Routed Board and Diagnose Routing Failures give post-route QA and failure root-causing. Backend, model, and effort selectors control every AI run and persist with the dialog settings (model/effort remembered per backend). - Placement - Place (AI) and Place + Route (AI) run
/plan-pcb-placement place/fullheadless into akrt_placement/folder beside the board. The tab shows the seed candidates with a preview, a status line read from the run's milestone ledger, and at the end REPORT.md; Apply Result to Board moves the open board's parts to the result's poses and locks (and, after Place + Route, its routed copper). These two need Claude Code. Beautify Labels (no AI) tidies the reference-designator silkscreen (py_placer/beautify_labels.py). - Save / Load a plan - Saveβ¦ writes the generated step list to a JSON file; Loadβ¦ reads one back and runs it with no Claude call β handy for replaying a workflow that worked on another board. A recorded command chain converts to a loadable plan too (
python3 py_router/make_plan.py <run dir>; see Plans from the command line). - Per-field "Ask AI" buttons - power nets/widths (Route tab), stackup check (Layers), differential-pair verification by pin function (Differential tab), net-to-plane layer mappings and GND return via distance (Planes tab).
The full button-to-skill map is in Claude Skills - Plugin GUI Integration. Datasheet-based skills use web lookups and take a few minutes; every run shows a live transcript with cancel.
Three ways to install:
A. KiCad Plugin and Content Manager (PCM) β the recommended path for end users, and it needs no extra repository URL: the package has been in the official KiCad repository (the one KiCad ships with, gitlab.com/kicad/addons) since v0.15.6. Open the PCM from the KiCad main window, leave the repository dropdown on KiCad official repository, go to the Plugins tab, search for routing, select KiCad Routing Tools and click Install, then Apply Changes at the bottom. If it is not listed, the PCM is serving a cached catalogue β press Refresh and look again. Versions are published with status testing rather than stable, which the PCM shows in the Status column but does not hide or block; kicad_version is a minimum, so the 9.0 entry installs on KiCad 10 as well. On first launch, the plugin checks the Python packages listed in requirements.txt (numpy, scipy, shapely, and the optional Pillow, without which only board renders and the placement preview are off) and offers a one-click pip install for any that are missing or too old into KiCad's Python. Do not assume KiCad supplies them: what it bundles varies by version and platform, and KiCad 10 on macOS ships no numpy at all. The check reports the version and the file path the running interpreter imports β KiCad's Python is often not the one pip show numpy answers for in a terminal.
B. PCM "Install from Fileβ¦" using the release zip β for a release newer than the one the official catalogue currently carries, for a pinned older version, or for an offline machine. Each GitHub Release ships a ready-to-install PCM package zip named KiCadRoutingTools-<version>.zip (a single cross-platform archive bundling the prebuilt Rust binaries for all platforms β not the auto-generated "Source code (zip)"). To install it:
- From the Release's Assets, download
KiCadRoutingTools-<version>.zip(e.g.KiCadRoutingTools-0.15.13.zip). - In KiCad, open Plugin and Content Manager from the main window.
- Click Install from File⦠(bottom of the PCM dialog) and select the downloaded zip.
- Click Apply Pending Changes, then restart KiCad if prompted.
The plugin appears under Tools β External Plugins in the PCB Editor. The same first-launch scipy/shapely dependency check described in (A) applies. This path keeps the plugin manageable from the PCM (you can update or uninstall it there), unlike the manual install below.
C. Manual install from source β for development or for using the CLI tools as well:
# Install the plugin (copies to KiCad plugins directory)
python3 install_plugin.py
# For development: create symlink instead of copying
python3 install_plugin.py --symlink
# Remove the plugin
python3 install_plugin.py --uninstall
# Skip installing the Python dependencies
python3 install_plugin.py --no-depsThe installer installs into every KiCad version it finds (version directories and install roots are discovered, not taken from a fixed list), under:
- macOS:
~/Documents/KiCad/<version>/3rdparty/plugins/ - Linux:
~/.local/share/kicad/<version>/3rdparty/plugins/ - Windows:
~/Documents/KiCad/<version>/3rdparty/plugins/
The installer also installs requirements.txt into KiCad's Python with pip, and skips pip when that Python already has everything. On Linux, KiCad runs the system Python, which Debian 12+, Ubuntu 23.04+, Fedora 38+ and Arch mark as externally managed (PEP 668) so pip refuses to install into it; there the installer runs no pip and prints the apt / dnf / pacman command for whatever is missing, plus the explicit --break-system-packages override for a package your distribution does not carry.
If you previously installed this plugin through the Plugin & Content Manager, that copy sits next to the local install and would shadow it on sys.path (causing stale-code errors). The installer detects any such PCM copy and moves it aside to <kicad-base>/disabled_pcm_plugins/<version>/, leaving it recoverable. Pass --keep-pcm to skip this.
The full release flow β version bump, GitHub Release, and the merge request to the official KiCad PCM repository β is documented step by step in docs/release-pipeline.md.
Short version:
- Bump
VERSIONand theversions[]entry inmetadata.json(andrust_router/Cargo.tomlonly when the Rust crate changed);python3 check_release_version.py --tag vX.Y.Zchecks they agree. git tag v0.15.6 && git push --tagsβ CI builds all 4 platform binaries, packages a singleKiCadRoutingTools-<ver>.zip(the PCM validator rejects duplicate version strings, so we ship one cross-platform zip), patchesmetadata.jsonwith real sha256/size values, and attaches everything to the GitHub Release.- Append the new version to the metadata file in your fork of
gitlab.com/kicad/addons/metadataand open an MR. See the docs page for the exact commands.
To build a zip locally for testing:
python3 package_pcm.py --binary-dir ./path/to/release/artifacts- Open KiCad (9.0 or later)
- Open a PCB in Pcbnew
- (Optional) Select one or more nets in the PCB editor first β for example by clicking tracks/pads, or right-clicking a track and choosing Select β All Tracks in Net. Any nets you have selected are automatically pre-checked for routing when the plugin opens.
- Go to Tools β External Plugins β KiCadRoutingTools
- To route the whole board hands-off: Auto βΊ Autorouter βΊ Run Autorouter, review its steps, then Apply Result to Board
- Or, by hand: configure routing parameters, select (or adjust) the nets to route, and click Route on the Route tab
Auto Tab (the first tab; a fresh dialog opens on it, a reopened one on the page it was closed on):
- Autorouter sub-tab: route the whole board with no agent. Run Autorouter runs
autoroute.pyas a subprocess on a snapshot of the open board (with its.kicad_pro/.kicad_dru), in a temp work folder. Its Plan pane shows what it read off the board -- the design rules and where they came from, the planes, the parts it fans out and the ones it does not, with why, the diff pairs and power nets -- and its Steps checklist one row per step, pending / running (time ticking) / done / FAILED / skipped, with each step's result (escapes and grazes, caps moved, pairs routed, each route pass's open nets and DRC, which pass shipped, why a pass did not run); the rows the run adds (a fanout's next rung, a re-fan) appear as they start. Selecting a row shows its command line, decisions, summary and log tail (a failed one its exit code and error). Options: Finish only (--finish), Effort factor (--effort-factor), Plane layer cost (--plane-layer-cost), Board's own rules (--board-rules), Keep placement (--keep-placement), Write filled zones (--write-fill). Stop kills the run and its steps. Apply Result to Board makes the open board match the shipped result -- footprint poses (the decap step moves caps), tracks and vias (live copper the result does not have is removed), the zones with their fills (not refilled), and the design rules the result was graded against -- after listing every change. - AI Routing sub-tab: plan a routing chain with
/plan-pcb-routingand run its steps; review and diagnose; save/load plans (see AI assistance above) - AI Placement sub-tab: place (and route) the board with
/plan-pcb-placement - Labels sub-tab: Beautify Labels -- uniform, non-overlapping reference-designator silkscreen, the CLI's
py_placer/beautify_labels.py
Route Tab:
- Net selection with filtering and component filtering
- Nets selected in the PCB editor before opening the plugin are pre-checked automatically (also applies to the Fanout, Planes, and Differential tabs)
- Option to separate nets by net class (organizes into tabs per class)
- Track width, clearance, via size/drill from net class or manual override; impedance; the fab tier, escalation policy and clearance ceiling (the CLI's
--fab-tier,--escalation,--clearance-ceiling) - Layer selection with per-layer cost multipliers
- Options: stub layer swaps, copper text moving, teardrops, DRC-settings fix, power net widths and neck-down, no-BGA zones, smoothing
- Guide corridor - draw a polyline on a User layer (e.g.
User.1) and tick "Follow User-layer guide path" to route the selected nets along it (waypoints, avoiding obstacles, packed non-overlapping) - Keepout zones - draw one or more closed polygons on a User layer (e.g.
User.2) and tick "Keep out of User-layer polygon(s)" to keep routed tracks out of those areas (hard keepout, all routed nets) - Clear guide/keepout layers - optional "Clear guide layer after routing" / "Clear keepout layer after routing" checkboxes (unchecked by default) delete the drawn guide/keepout graphics from their User layer after a successful route, so you can draw fresh ones for the next run
Advanced Tab:
- Swappable nets configuration for target swap optimization
- Routing parameters: iterations, heuristic weight, rip-up, probe iterations
- MPS ordering options, direction control, length matching
- Proximity settings: BGA, stub, track, via proximity costs
- Debug options
Differential Tab:
- Differential pair selection with filtering
- Pair width and gap, differential impedance, turning radius, setback angle configuration
- Options: polarity fix, GND vias, intra-pair length matching, AC-coupled end-to-end matching
- Ask AI confirms pairs by pin function
Fanout Tab:
- BGA fanout with exit margin, escape direction, differential pair support, and plane-net ball drops
- Escape method: auto (channel router, under-pad retry), channel, under-pad for dense fully-populated BGAs (issue #122), or dog-bone β see BGA Fanout
- "Optimize decoupling cap placement" option (off by default) β after fanout, nudges decoupling caps off foreign-net fanout vias and toward same-net balls β see Decap Clearance Repair
- QFN fanout with extension length, escape layer, and an under-pad (via-drop) escape
- Net selection for fanout operations
Planes Tab (pour creation only since #562 β plane repair runs inside every route, and the route step welds plane pads into the pour):
- Net-to-layer assignment for power/ground planes (Ask AI recommends one)
- Create the pours (plus thermal via arrays under exposed pads, optional thermal-relief connections)
- Area via stitching, a board-edge via fence, and GND return via placement near signal vias
- Via size/drill, zone clearance configuration
Log Tab:
- Real-time routing output display
- Color-coded messages (errors, warnings, success)
About Tab:
- Version information and credits
- Window transparency, Validate PCB Data (the pcbnew-built board model against the file parser's, reported in the Log tab) and Reset All Settings to Defaults
General Features:
- Settings persistence (parameters and selections preserved between sessions)
- Cancel button to stop routing operations mid-progress
- Results applied directly to the open PCB in KiCad
All --nets options support fnmatch-style wildcards and exclusion patterns:
| Pattern | Description |
|---|---|
* |
All nets |
*DATA* |
Nets containing "DATA" |
/* |
Nets starting with "/" (hierarchical) |
Net-(U1-*) |
Nets matching "Net-(U1-...)" |
!GND |
Exclude net named "GND" |
!*VCC* |
Exclude nets containing "VCC" |
"*" "!GND" "!VCC" |
All nets except GND and VCC |
Notes:
- Exclusion patterns (starting with
!) remove matching nets from the result - Order matters: include patterns add nets, exclude patterns remove them
- Nets starting with "unconnected-" are automatically excluded
- Use quotes around patterns with special characters
autoroute.py routes a whole board with no agent (the other way is the
/plan-pcb-routing skill): it reads the board's rules, footprints and nets, plans the
chain (planes, fanouts, decap clearance, diff pairs, route passes) and runs it, each
step as its own process. The commands below are the tools it runs, for a hand-built
chain.
python3 py_router/autoroute.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb
python3 py_router/autoroute.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --dry-run# Route all nets (default) - outputs to input_routed.kicad_pcb
python3 py_router/route.py kicad_files/input.kicad_pcb
# Route all nets, overwrite input file
python3 py_router/route.py kicad_files/input.kicad_pcb --overwrite
# Route all nets to a specific output file
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb
# Route specific nets (using --nets option)
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "Net-(U2A-DATA_0)" "Net-(U2A-DATA_1)"
# Route with wildcard patterns
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "Net-(U2A-DATA_*)"
# Route all nets on a component (auto-excludes GND/VCC/VDD/unconnected)
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --component U1
# Route specific patterns on a component (no auto-exclusion)
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "/DDAT*" --component U1
# Route ALL nets on a component including power (use "*" pattern)
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "*" --component U1
# Exclusion-pattern SYNTAX demo (! prefix). NOTE: in the #562 chain you do
# NOT exclude plane nets from the route step -- see the chain example below.
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "*" "!GND" "!VCC"
# Route one placement BLOCK -- a schematic sheet, a KiCad group, a net-name prefix, an IC and
# its decaps (--group-by kicad,sheet,netprefix,decap; auto = kicad,sheet; --list-groups shows them)
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb \
--group-by sheet --list-groups # what blocks exist?
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb \
--group sheet:558c3023 --group-by sheet --group-scope internal
# PREVIEW any routing run: route it, report what it WOULD add, write no board
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb \
--group sheet:558c3023 --group-by sheet --preview --preview-png preview.png
# UNDO: strip the scoped nets' copper back to unrouted (needs an explicit scope;
# defaults to --group-scope internal, since a block's "touching" nets include
# GND/VCC and undoing those would strip their copper across the whole board)
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/undone.kicad_pcb \
--group sheet:558c3023 --group-by sheet --undo
# Route differential pairs (use route_diff.py)
python3 py_router/route_diff.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "*lvds*" --no-bga-zones
# Route with wider tracks for power nets
python3 py_router/route.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets "Net*" \
--power-nets "*GND*" "*VCC*" "+3.3V" --power-nets-widths 0.4 0.5 0.3 --track-width 0.2
# Typical workflow: create GND plane first, then route all signals
python3 py_router/route_planes.py kicad_files/flat_hierarchy.kicad_pcb --nets GND --plane-layers B.Cu
python3 py_router/route.py kicad_files/flat_hierarchy_routed.kicad_pcb --overwrite# Pour a GND zone on B.Cu (outputs to input_routed.kicad_pcb). The pour places no
# per-pad taps: the route step that follows welds the plane pads into it (#562)
python3 py_router/route_planes.py kicad_files/input.kicad_pcb --nets GND --plane-layers B.Cu
# Create GND zone, overwrite input file
python3 py_router/route_planes.py kicad_files/input.kicad_pcb --overwrite --nets GND --plane-layers B.Cu
# Create GND zone to specific output file
python3 py_router/route_planes.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb --nets GND --plane-layers B.Cu
# Create multiple planes at once (each net paired with corresponding plane layer)
python3 py_router/route_planes.py kicad_files/input.kicad_pcb --nets GND +3.3V --plane-layers In1.Cu In2.Cu
# VCC plane; --via-size/--via-drill size this step's own vias (thermal arrays, stitching)
python3 py_router/route_planes.py kicad_files/input.kicad_pcb --nets VCC --plane-layers In2.Cu --via-size 0.5 --via-drill 0.4
# Multiple nets sharing one layer, split round spines routed on it (use | separator)
python3 py_router/route_planes.py kicad_files/input.kicad_pcb --nets GND "VA19|VA11" --plane-layers In4.Cu In5.Cu
# Dry run to see what would be placed
python3 py_router/route_planes.py kicad_files/input.kicad_pcb --nets GND --plane-layers B.Cu --dry-runGND return vias (--add-gnd-vias) and area stitching (--stitch-vias, --stitch-edge-fence) go in a re-run of the same pour after routing, so they place around the finished signals, and a return via needs GND poured on two layers β see Plane Routing.
Since #562 you normally do not run this step. Every
route.pyrun finishes with an in-run plane finalize that applies this same engine (pad taps + region joins), the plane-copper cleanup, and a KiCad-oracle completion check β so a pours-first chain repairs its planes automatically.KICAD_PLANE_FINALIZE=0is the kill switch. The finalize runs even when the route step finds nothing else to route (#1112), so a chain should end onroute.py, never on this script. Use the standalone script below for a board routed OUTSIDE that chain (e.g. hand-edited copper); its track and via default to the board's Default net class, not to the sizes a chain routed at, so pass--track-width/--via-size/--via-drillif they differ.
After creating power planes, regions may become split by vias and traces from other nets. Use repair_planes.py to reconnect them:
# Auto-detect all zones in PCB and repair disconnected regions (outputs to input_routed.kicad_pcb)
python3 py_router/repair_planes.py kicad_files/input.kicad_pcb
# Auto-detect all zones, overwrite input
python3 py_router/repair_planes.py kicad_files/input.kicad_pcb --overwrite
# Auto-detect all zones to specific output file
python3 py_router/repair_planes.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb
# Specific nets and layers
python3 py_router/repair_planes.py kicad_files/input.kicad_pcb --nets GND --plane-layers B.Cu
# Customize track width and clearance
python3 py_router/repair_planes.py kicad_files/input.kicad_pcb kicad_files/output.kicad_pcb \
--track-width 0.5 --clearance 0.2Placement deltas are invisible in a board file; render them instead.
# what moved, and did it help? (ghosts at the seed poses, arrows, metrics caption)
python3 py_tools/render_placement.py placed.kicad_pcb --before seed.kicad_pcb -o delta.png
# zoom to one placement block; same block names as route.py --group
python3 py_tools/render_placement.py board.kicad_pcb --list-groups --group-by sheet
python3 py_tools/render_placement.py board.kicad_pcb --zoom-group sheet:58d913ec --per-side -o out/
# everything a placement author reads, in one artifact: escape lanes, groups, and
# lock advice (which parts should NOT move) -- locks nothing, writes no board
python3 py_tools/board_brief.py board.kicad_pcbToggles for --borders / --labels / --ratsnest / --arrows / --ghosts;
--per-side gives F and B panels rather than one flattened projection.
The render is triage, and so are the caption's crossings / hpwl: a
placement is judged by routing it.
# Check for DRC violations. With no -c, grades at the Default net-class clearance
# the routing steps wrote into the sibling .kicad_pro (the clearance the board was
# routed to), plus the board's .kicad_dru layer rules; falls back to 0.2mm if
# there's no project. Pass -c to override.
python3 py_router/check_drc.py kicad_files/output.kicad_pcb
# Cross-check with KiCad's own DRC engine (requires KiCad; --refill-zones avoids
# bogus zone-clearance errors from stale pours - see tests/README.md for details)
kicad-cli pcb drc --refill-zones --format json -o drc.json kicad_files/output.kicad_pcb
# ...because a routed board ships zone OUTLINES with no filled_polygon, so an
# unrefilled grade reports plane opens that are not real (#910). To ship a
# board that already carries its fills, add --write-fill to the route step, or:
python3 py_tools/fill_for_delivery.py kicad_files/output.kicad_pcb -o delivered.kicad_pcb
# Check connectivity (detects unrouted nets, broken routes, and T-junctions)
python3 py_router/check_connected.py kicad_files/output.kicad_pcb
# Check connectivity for specific nets
python3 py_router/check_connected.py kicad_files/output.kicad_pcb --nets "*DATA*"
# Check connectivity for all nets on a component
python3 py_router/check_connected.py kicad_files/output.kicad_pcb --component U1
# Only check routed nets (skip unrouted net detection)
python3 py_router/check_connected.py kicad_files/output.kicad_pcb --routed-only
# Check for orphan stubs (dead-end traces with no pad/via/trace at the loose end).
# Connection is judged by actual copper extent (via radius, pad size, trace
# half-width), so T-junction taps and copper-overlap joints are not miscounted.
python3 py_tools/check_orphan_stubs.py kicad_files/output.kicad_pcb
# Other-net copper inside the screw-head ring of each mounting hole (KiCad checks
# a hole's clearance only). Declare the ring before routing with
# add_rule_area.py --name MOUNT --mounting-holes. --ring MM sets how far past the
# hole edge the head reaches (default 0.4 x the drill).
python3 py_tools/check_mounting_holes.py kicad_files/output.kicad_pcb --ring 1.3
# Pad-geometry sanity check: flags same-footprint, different-net pads whose copper
# overlaps (a short). A non-zero result almost always means a pad's rotation/size
# is modelled wrong - the usual cause is a QFN/QFP/BGA placed at a non-orthogonal
# angle. The fanout tools run this automatically on their component first; run it
# yourself before fanout (or board-wide) as a standalone check:
python3 py_router/check_pads.py kicad_files/board.kicad_pcb # whole board, per footprint
python3 py_router/check_pads.py kicad_files/board.kicad_pcb --component U23 # one footprint
python3 py_router/check_pads.py kicad_files/board.kicad_pcb --cross-footprint # also across parts
# Flag long non-orthonormal tracks. An on-grid router emits only 0/45/90-degree
# segments; the only legitimate non-orthonormal segment is a short (<=1 grid cell)
# terminal connector to an off-grid pad/ball. Anything longer is a routing defect
# (it can cut diagonally across foreign copper). qfn_fanout escape stubs are
# excluded automatically; bga_fanout's short stub-end jogs clear the 0.25mm default.
python3 py_tools/check_orthonormal.py kicad_files/output.kicad_pcb
# Copper hygiene (read-only): dangling stubs, same-net soft joints, redundant
# cycles, and removable / stacked / floating copper the routing left behind.
python3 py_router/check_weird.py kicad_files/output.kicad_pcb
# Is the board DONE? One verdict over board_score and the checkers above, which
# fails closed: exit 0 done, 4 incomplete, 5 graded clean only against floors
# the routing lowered (--authored-from names the board the chain started from)
python3 check_complete.py kicad_files/output.kicad_pcb --authored-from kicad_files/input.kicad_pcbSee Utilities for every checker and its options, and
python3 krt_registry.py for every runnable tool in the clone with its purpose.
Use the /analyze-power-nets skill to identify power nets and get track width recommendations:
# Ask the AI to analyze your board with datasheet lookup
/analyze-power-nets kicad_files/my_board.kicad_pcb
The skill:
- Auto-classifies obvious components (resistors, capacitors, inductors, etc.)
- Uses WebSearch to look up datasheets for unknown components (ICs, connectors, transistors)
- Classifies each component's role (power source, current sink, pass-through, shunt)
- Traces power paths from sinks to sources
- Generates ready-to-use
--power-netsconfigurations
See Power Net Analysis for detailed documentation.
Use the /find-high-speed-nets skill to identify high-speed nets and get GND return via recommendations:
# Ask the AI to analyze signal speeds with datasheet lookup
/find-high-speed-nets kicad_files/my_board.kicad_pcb
The skill:
- Pre-classifies nets by name patterns (DDR, USB, SPI, CLK, etc.)
- Pre-classifies components by footprint (FPGA, DDR, PHY, etc.)
- Uses WebSearch to look up datasheets for ICs and extract max clock rates and rise times
- Traces high-speed signals through series passives (termination resistors, AC coupling caps)
- Generates a speed classification (ultra-high/high/medium/low) with recommended
--gnd-via-distance
The /plan-pcb-routing skill includes a lightweight version of this analysis (net name and
footprint pattern matching only, no datasheet lookup) and automatically includes a GND return
via step when GND planes are present. Run /find-high-speed-nets first for more accurate
recommendations based on actual component specifications.
# Run full integration test (fanout + routing + checks)
python3 tests/test_fanout_and_route.py --all
# Quick mode for faster testing
python3 tests/test_fanout_and_route.py --all --quick
# The whole suite (~770 files, about 40 minutes on one machine when last measured)
python3 tests/run_all.pySee tests/README.md for detailed documentation of all test scripts.
The documentation index is organised by task (install, route, place, check, test, release); the table below describes each document.
| Document | Description |
|---|---|
| Routing Architecture | Module structure, obstacle maps, A* algorithm |
| Python API | Using the modules as a library: parser, writer, modification, config, net analysis, impedance β with runnable examples |
| Configuration | Command-line options, GridRouteConfig parameters |
| Differential Pairs | P/N pairing, polarity swaps, via handling |
| Net Ordering | MPS algorithm, inside-out ordering, strategy comparison |
| Rip-Up and Reroute | Blocking analysis, progressive N+1 escalation, reroute loop |
| Length Matching | Trombone meanders, via barrel lengths, DDR auto-grouping, time matching |
| Bus Routing | Bus detection and filter, corridor planning, middle-out ordering, corridor attraction; the topo bus step |
| Guide Corridor | User-layer guide paths, waypoints, best-effort following |
| Power/Ground Planes | Copper zones with automatic via placement |
| Utilities | Every checker (DRC, connectivity, completion, hygiene, pads), the fanout generators, placement tools, renderers, the DRC-settings fixer |
| Design Brief | Declare what the board IS -- the facts a board file cannot contain -- and compile them into the intent (<board>.design-brief.json) |
| Floorplan Intent | Declare the floorplan, grade the board against it (check_floorplan.py) |
| BGA Fanout | BGA escape routing generator |
| QFN Fanout | QFN/QFP escape routing generator |
| Rust Router | Building and using the Rust A* module |
| Power Net Analysis | Power net detection, AI analysis, track width guidelines |
| Claude Skills | All eleven AI skills: placement and routing end to end, routing plans, power/high-speed/diff-pair analysis, stackup, plane mappings, failure diagnosis, board review, the 3D movie |
| Placement | Placement by function: groups, one annealed objective, legality, the floorplan intent's grade |
| Integration Tests | Test scripts and performance benchmarks |
| Release Pipeline | How to tag a release and submit it to the KiCad PCM (maintainers) |
KiCadRoutingTools/
βββ py_router/ # Routing engine + CLI entry points (~130 modules)
β βββ route.py # Main CLI - single-ended routing (ends with the in-run plane finalize, #562)
β βββ route_diff.py # Main CLI - differential pair routing
β βββ route_planes.py # Main CLI - power/ground plane pours
β βββ repair_planes.py # Standalone utility - repair disconnected plane regions (the chain step is absorbed into route.py's finalize, #562)
β βββ route_render.py # PNG still of a board from its geometry
β βββ route_movie.py # Movie of a routing run, step by step (route_trace.py records the router's events)
β βββ make_plan.py # Recorded command chain -> GUI routing plan (plan.json)
β βββ run_plan.py # Run a GUI routing plan headless, through the real plugin dialog
β βββ autoroute.py # Build a routing chain from the board itself and run it, no agent
β βββ add_rule_area.py # Write a copper keep-out rule area onto a board
β βββ plane_io.py # Plane I/O utilities (zone extraction, output writing)
β βββ plane_obstacle_builder.py # Obstacle map building for plane via placement
β βββ plane_blocker_detection.py # Blocker detection and rip-up for plane vias
β βββ plane_zone_geometry.py # Voronoi cells for a shared plane layer's split
β βββ plane_split_raster.py # Raster finishing of a shared plane layer's split
β βββ plane_resistance.py # Plane resistance and current capacity calculations
β βββ plane_region_connector.py # Detect and route between disconnected plane regions
β βββ routing_config.py # GridRouteConfig, GridCoord, DiffPairNet classes
β βββ routing_defaults.py # Default routing parameter values
β βββ routing_state.py # RoutingState class - tracks routing progress
β βββ routing_common.py # Shared utilities for route.py and route_diff.py
β βββ obstacle_map.py # Obstacle map building functions
β βββ obstacle_cache.py # Net obstacle caching for incremental builds
β βββ diff_pair_loop.py # Differential pair routing loop
β βββ single_ended_loop.py # Single-ended routing loop
β βββ reroute_loop.py # Reroute queue processing
β βββ diff_pair_routing.py # Diff pair A* routing implementation
β βββ single_ended_routing.py # Single-ended A* routing implementation
β βββ net_ordering.py # MPS, inside-out, and original ordering
β βββ rip_up_reroute.py # Rip-up and reroute logic
β βββ length_matching.py # Length matching with trombone meanders
β βββ kicad_parser.py # KiCad .kicad_pcb file parser
β βββ kicad_writer.py # KiCad S-expression generator
β βββ output_writer.py # Route output and swap application
β βββ pcb_modification.py # Add/remove routes from PCB data
β βββ impedance.py # Impedance calculation (microstrip/stripline formulas)
β βββ check_drc.py # DRC violation checker
β βββ check_connected.py # Connectivity checker (with T-junction detection)
β βββ check_pads.py # Pad-geometry sanity checker
β βββ check_weird.py # Copper hygiene checker
β βββ cleanup_pipeline.py # The one ordered post-route cleanup pipeline (both routing fronts)
β βββ fix_kicad_drc_settings.py # Make .kicad_pro DRC constraints consistent with the routed floors
β βββ copy_board.py # Copy a board WITH its sibling .kicad_pro/.kicad_dru
β βββ list_nets.py # List nets on a component
β βββ startup_checks.py # Startup checks (Python deps, Rust library version)
β βββ bga_fanout.py # BGA fanout CLI wrapper
β βββ bga_fanout/ # BGA fanout package (escape, reroute, layer balance, under-pad escape, ...)
β βββ qfn_fanout.py # QFN/QFP fanout CLI wrapper
β βββ qfn_fanout/ # QFN/QFP fanout package (layout, geometry, types)
β βββ ... # plus the rest of the engine modules β see Module Overview below
β
βββ py_placer/ # Placement CLIs and the placement package
β βββ place_simple.py # The placer: functional groups, one objective, annealed
β βββ place_movie.py # place_simple with a camera: a movie of the placement, step by step
β βββ judge_seeds.py # The seed judge: judge.json's seeds routed by one quick chain, scored
β βββ place_pose.py # Set, turn, face, lock or replicate parts by hand
β βββ place_fanout_clearance.py # Move decoupling caps off fanout vias
β βββ beautify_labels.py # Tidy the reference-designator silkscreen
β βββ converge.py # The milestone ledger: record, where, verdict
β βββ placement/ # Component placement package β see py_placer/placement/README.md
β β βββ simple.py # The placer's cost model
β β βββ simple_anneal.py # The placer's simulated annealing
β β βββ quench.py # QuenchState: the parts, their poses and the board
β β βββ grouping.py # The groups file
β β βββ legality.py # Placement legality checks
β β βββ floorplan.py # Floorplan intent and its grade
β β βββ body.py # THE footprint body model (#896)
β β βββ fanout_clearance.py # Fanout clearance evaluation
β β βββ parser.py # Courtyard boundary extraction
β β βββ writer.py # Footprint position modification
β β βββ ...
β βββ ...
β
βββ py_tools/ # Leaf diagnostic / analysis tools
β βββ check_impedance.py # Verify impedance-controlled widths/gaps
β βββ check_orphan_stubs.py # Orphan stub detector
β βββ check_mounting_holes.py # Other-net copper under a mounting hole's screw head
β βββ check_cycles.py # Redundant-loop (cycle) + overlapping-via checker
β βββ check_orthonormal.py # Long non-orthonormal track detector
β βββ net_forensics.py # Per-net copper forensics
β βββ kicad_unconnected.py # Unconnected-item listing
β βββ validate_pcb_data.py # PCBData validation
β βββ extract_pcb_geometry.py # Geometry extraction
β βββ clean_ignored.py # List / delete git-ignored files
β βββ analyze_power_paths.py # Power-path analysis (backs /analyze-power-nets)
β βββ board_brief.py # What a board looks like to whatever places it
β βββ board_context.py # Every part's value, pins, nets and role
β βββ check_groups.py # Check a groups file against its board
β βββ check_floorplan.py # Grade a board against its floorplan intent
β βββ check_assembly.py # Is a placement buildable?
β βββ render_placement.py # PNG stills of a placement, with its legality
β βββ route_review.py # What to move after a route
β βββ render_nets.py # Chosen nets' copper on several boards side by side
β βββ render_power.py # A board's power components over its rails
β βββ board_score.py # One score for a board: blocking, then quality
β βββ quick_score.py # Score a route.py --quick 2 board (the placement seed judge)
β βββ check_reachability.py # Is this pad reachable, or is the geometry to blame?
β βββ check_join.py # Verify a hand-drawn join against all board copper before committing it
β βββ fill_for_delivery.py # Write a filled copy of a routed board (#910)
β βββ _path.py # sys.path bootstrap so the tools import py_router
β
βββ tests/ # Tests (~770 files) and the stress/A-B harness
β βββ run_all.py # The whole suite (tests/stress/modal_suite/ fans it out onto Modal)
β βββ test_fanout_and_route.py # Full integration test (fanout + route)
β βββ test_kit_route.py # Pad-to-pad routing test (no fanout)
β βββ test_flat_hierarchy.py # 2-layer board with GND plane test
β βββ test_interf_u.py # 2-layer board with non-rectangular outline test
β βββ test_sonde_u.py # Wide track routing test
β βββ run_utils.py # Shared test utilities
β βββ gui_parity/ # CLI/GUI parity gates β see tests/gui_parity/README.md
β βββ stress/ # Real-world-board stress-test harness (run_queue.sh) β see tests/README.md
β
βββ rust_router/ # Rust A* implementation
βββ kicad_routing_plugin/ # KiCad ActionPlugin
β βββ action_plugin.py # ActionPlugin entry point
β βββ swig_gui.py # Main routing dialog (Route/Advanced tabs)
β βββ differential_gui.py # Differential pair routing tab
β βββ fanout_gui.py # BGA/QFN fanout tab and net selection panel
β βββ planes_gui.py # Power/ground planes tab
β βββ tab_names.py # The dialog's page and sub-tab names, in order
β βββ autoroute_gui.py # Auto tab, Autorouter sub-tab (runs autoroute.py on a snapshot, shows its steps)
β βββ result_apply.py # Apply Result to Board: poses, tracks/vias, zones, rules from a result file
β βββ ai_gui.py # Auto tab, AI Routing sub-tab (spawns the agent CLI headless, streams transcript)
β βββ ai_plan.py # Routing plans: parse, fill the tabs, run the steps (PlanExecutor)
β βββ placement_gui.py # Auto tab, AI Placement sub-tab
β βββ labels_gui.py # Auto tab, Labels sub-tab (Beautify Labels)
β βββ placement_run.py # Placement run folders, prompts and progress (krt_placement/)
β βββ ai_backend.py # Agent CLI backend selection (Claude Code / opencode)
β βββ board_swaps.py # Shared board pad/net swap helpers
β βββ deps_check.py # Plugin dependency checks
β βββ about_tab.py # About tab with version info
β βββ gui_utils.py # Shared GUI utilities
β βββ settings_persistence.py # Save/restore dialog settings between sessions
βββ build_router.py # Rust module build script (--clean to remove artifacts)
βββ install_plugin.py # Plugin installer script
βββ check_complete.py # Is this board DONE? One fail-closed verdict
βββ krt_registry.py # Every runnable tool in the clone, its purpose and kind
βββ krt_capabilities.py # What this clone can do, as JSON (also route.py --capabilities)
βββ package_pcm.py # Build the KiCad PCM zip (maintainers)
βββ requirements.txt # Python dependencies
βββ kicad_files/ # Example and test boards
βββ docs/ # Documentation
βββ .claude/skills/ # Claude Code skills
βββ analyze-power-nets/ # AI-powered power net analysis skill
βββ find-high-speed-nets/ # AI-powered high-speed net identification skill
βββ plan-pcb-routing/ # AI-powered routing plan generation skill (orchestrates the others)
βββ identify-diff-pairs/ # Datasheet-based diff pair detection skill
βββ recommend-stackup/ # Stackup review/recommendation skill
βββ recommend-plane-mappings/ # Net-to-plane-layer assignment skill
βββ diagnose-routing-failures/ # Failure root-cause and retry skill
βββ plan-pcb-placement/ # Place by function, fast-route seeds, keep the best, route; one verifier, report
βββ review-routed-board/ # Post-route QA and sign-off skill
βββ stress-test-router/ # Batch stress-test on real-world boards + issue filing (dev/QA)
One-line summaries below (all of these modules live in py_router/); the
Python API documentation has full per-module references
(signatures, dataclass fields, gotchas) with runnable examples.
| Module | Purpose |
|---|---|
route.py |
CLI for single-ended routing |
route_diff.py |
CLI for differential pair routing |
route_planes.py |
CLI for power/ground plane pours (#562 bare pour), thermal via arrays, stitching and GND return vias |
repair_planes.py |
CLI for repairing disconnected plane regions on a board routed outside the chain (route.py's in-run plane finalize runs the same engine) |
routing_config.py |
Configuration classes (GridRouteConfig, GridCoord, DiffPairNet) |
routing_defaults.py |
Every default routing parameter, in one place (FAB_TIER, ESCALATION, CLEARANCE, ...) |
design_rules.py |
KiCad design rules resolved in KiCad's own order (#530): pad overrides, net classes, .kicad_dru rules, Board Setup minimums |
kicad_dru.py |
Per-layer clearance rules from the board's .kicad_dru (#498) |
fab_tiers.py |
Fab-capability floors (--fab-tier) and the escalation policy (--escalation) |
routing_state.py |
RoutingState class tracking progress, results, and PCB modifications |
routing_context.py |
Helper functions for building obstacles and recording success |
routing_common.py |
Shared utilities for route.py and route_diff.py (BGA zones, net resolution, length matching) |
routing_utils.py |
Shared utilities (build_layer_map, iter_pad_blocked_cells) |
obstacle_map.py |
Obstacle map building from PCB data |
obstacle_cache.py |
Net obstacle caching for incremental obstacle map builds |
obstacle_costs.py |
Stub and track proximity cost calculations |
sense_branch.py |
Protected Kelvin sense branches (#1279), declared by a KiCad group named sense:<REF>.<PAD> (the join pad): the member copper and its sense pads are foreign to their own net except on the join pad, so new copper joins the branch only there |
net_keepouts.py |
Net-filtered copper keep-outs from the board's .kicad_dru (disallow rules on a named rule area): the regions, stamped into the obstacle map only while a net a rule binds routes, and the audit of bound-net copper the shipped board has inside one |
area_clearance.py |
Clearance and track-width rules scoped by a rule area (A.insideArea('ROOM')), routed to as KiCad binds them, per item: the regions, the composition of every keep-out stamp over them (class values outside an area, the rule's value inside), the pair reading the post-route passes share, the split of a track where it leaves a tightened area, and the necking of a track where it needs a room's width |
keep_away.py |
Pairwise keep-away between net groups (#1146): the per-net band cost and the in-band report; the design brief's keep_away rules, read for the router and the placement grade alike (#1253) |
bresenham_utils.py |
Bresenham line-walking utilities for grid-based segment operations |
geometry_utils.py |
Shared geometry calculations (point-to-segment distance, segment intersection, UnionFind) |
routing_constants.py |
Shared constants (default layer stack, power net patterns, tolerances) |
terminal_colors.py |
ANSI color codes for terminal output |
| Module | Purpose |
|---|---|
diff_pair_loop.py |
Main loop for routing differential pairs |
single_ended_loop.py |
Main loop for routing single-ended nets |
reroute_loop.py |
Processes reroute queue for failed routes |
phase3_routing.py |
Phase 3 multi-point tap routing (connects remaining pads after length matching) |
diff_pair_routing.py |
Differential pair A* with centerline + offset and GND vias |
diff_pair_multipoint.py |
Multi-point and hybrid (coupled middle + single-ended legs) differential pairs |
single_ended_routing.py |
Single-ended net A* routing |
group_routing.py |
Route, preview and undo one placement block (route.py --group/--preview/--undo) |
| Module | Purpose |
|---|---|
net_ordering.py |
MPS, inside-out, and original net ordering strategies |
net_queries.py |
Net queries (diff pair detection, MPS ordering, power net detection, chip pad positions) |
connectivity.py |
Stub endpoints, connected groups, multi-point net detection, MST edges |
bus_detection.py / bus_corridor.py |
Bus groups of nets with clustered endpoints, and one planned centerline per bus (--bus) |
diff_xnet.py |
AC-coupled differential pairs (XNets) through series caps (#196) |
Key functions in net_queries.py:
identify_power_nets(pcb, patterns, widths)- Pattern-based power net detection for--power-netsCLI optioncompute_mps_net_ordering(pcb, net_ids)- MPS algorithm for optimal net orderingfind_differential_pairs(pcb, patterns)- Detect P/N pairs from net names (suffix-style aware:+/-nets only pair with each other, never with_P/_Nnets sharing the same base name)
Key functions in py_tools/analyze_power_paths.py (used by /analyze-power-nets skill):
analyze_pcb(filepath)- Load PCB and extract components for analysisget_components_needing_analysis(components)- Get components requiring AI classificationclassify_component(components, ref, role, current_rating_ma, notes, supply_nets, input_nets)- Set component classification (supply_netsnames the rails of a part whose pads carry no pintype and whose nets are not rail-named, a source's outputs;input_netsnames a source's inputs and replaces what its pins say)trace_power_paths(pcb, components)- Trace each load upstream (regulators entered output to input only) to the source feeding itget_power_net_recommendations(pcb, components, paths)- Get recommended track widths (a sink's rating is charged once per net; a source's rating is a limit, never a load)
| Module | Purpose |
|---|---|
layer_swap_optimization.py |
Upfront layer swap optimization before routing |
layer_swap_fallback.py |
Try layer swap when route fails |
stub_layer_switching.py |
Low-level stub layer swap utilities |
mps_layer_swap.py |
MPS-aware layer swap for crossing conflicts |
polarity_swap.py |
P/N polarity swap for differential pairs |
target_swap.py |
Hungarian algorithm for optimal target assignment |
rip_up_reroute.py |
Rip-up blocking routes and retry |
blocking_analysis.py |
Analyze which nets are blocking |
length_matching.py |
Length matching with trombone-style meanders |
| Module | Purpose |
|---|---|
net_rescue.py |
Last-chance scoped retry of failed nets at finer parameters, then the terminal geometry escalation |
finer_grid_rung.py |
The final reconciliation's last lap: nets still boxed in re-routed at half the run's grid, with rip authority over their blockers, under a cell budget (#1763) |
plane_pad_tap.py / plane_region_connector.py |
Plane pad taps and region joins: the engine of route.py's in-run plane finalize and of repair_planes.py |
kicad_oracle.py |
KiCad-oracle reconnect: routes the exact links KiCad's own connectivity reports open |
cleanup_pipeline.py |
The one ordered post-route cleanup pipeline both routing fronts run |
improvement_gate.py |
Never ship a board a run made worse (#600): reverts the step when connectivity regressed |
fix_kicad_drc_settings.py |
Write the routed floors into the output's .kicad_pro so KiCad's DRC grades what was routed |
protected_nets.py / tool_records.py |
Records later steps must honour (matched groups, routed pairs, impedance, pour promises), kept on the board and in the .kicad_pro |
| Module | Purpose |
|---|---|
kicad_parser.py |
KiCad .kicad_pcb file parser (extracts stackup, footprint values, pintypes) |
kicad_writer.py |
KiCad S-expression generator |
output_writer.py |
Write routed output with swaps and debug geometry |
pcb_modification.py |
Add/remove routes from PCB data structure |
schematic_updater.py |
Update .kicad_sch files with pad swaps from routing |
impedance.py |
Impedance calculations (microstrip/stripline, width from target Z) |
memory_debug.py |
Memory usage statistics and debugging |
route_render.py |
PNG still of a board from its geometry: the frame every picture and movie is drawn on |
route_trace.py |
With KICAD_ROUTE_TRACE=1, records each track and via as the router lays, rips and restores it (<output>_routetrace.json), for route_movie.py |
route_movie.py |
Movie of a routing run, step by step |
Integration test results (tests/test_fanout_and_route.py), as measured when this table was written in January 2026; the router has changed a great deal since, so read them as orders of magnitude:
| Stage | Nets | Time | Iterations |
|---|---|---|---|
| FTDI single-ended | 47/47 | 8.6s | 319K |
| LVDS diff pairs (batch 1) | 28/28 | 29.7s | 10.2M |
| LVDS diff pairs (batch 2) | 28/28 | 28.0s | 12.0M |
| DDR diff pairs | 5/5 | 0.3s | 25K |
| DDR single-ended | 51/51 | 6.2s | 565K |
Rust acceleration provided a ~10x speedup over the original pure-Python A*.
Every tool prints its accepted options with --help. Configuration
explains those options and their defaults. Use Routing Configuration API
for GridRouteConfig fields. The tool-specific guides go deeper on their area:
| Tool | Purpose | Guide |
|---|---|---|
route.py |
Single-ended routing | Configuration |
route_diff.py |
Differential-pair routing | Differential Pairs |
route_planes.py |
Power/ground plane pours, stitching, GND return vias | Plane Routing |
repair_planes.py |
Plane region repair + pad taps | Plane Routing |
bga_fanout.py / qfn_fanout.py |
BGA / QFN escape fanout | BGA Β· QFN Β· Utilities |
place_fanout_clearance.py |
Move decoupling caps off fanout vias | Utilities |
place_simple.py |
Place a board by its functional groups | Placement |
judge_seeds.py |
The seed judge: the seeds judge.json names routed by one quick (level 2) chain and scored | Utilities |
board_brief.py |
Assemble what a placement author needs to read, in one artifact | Utilities Β· Design Brief |
check_floorplan.py |
Grade a board against a declared floorplan intent | Floorplan Intent |
cover_facts.py |
What the board knows about a card or module over it: connector heights, card models and their undersides, standoffs on its axes, the parts under it | Floorplan Intent |
check_*.py |
DRC / connectivity / hygiene / pad checks | Utilities |
check_complete.py |
Is the board DONE? One fail-closed verdict over the checks | Utilities |
krt_registry.py |
Every runnable tool in the clone, what it is for, and which door (placement / routing) serves it | Utilities |
route_render.py |
PNG still of a board from its geometry | Utilities |
route_movie.py / place_movie.py |
Movie of a routing run / of a placement, step by step | Utilities |
render_power.py |
A board's power components over its rails | Utilities |
make_plan.py / run_plan.py |
Build a GUI routing plan from a recorded chain / run one headless | Plans from the CLI |
autoroute.py |
Route a board end to end with no agent: a plane, fanout, decap, diff-pair and route chain built from the board itself | Utilities |
# Full option list for any tool
python3 py_router/route.py --help
# A typical chain (#562 pours-first): pour, then diff pairs, then ONE route
# over ALL nets -- plane nets INCLUDED. The pour places no taps; the route
# step welds plane pads into the fill and its in-run finalize completes them,
# so do NOT exclude the plane nets here.
python3 py_router/route_planes.py board.kicad_pcb board.kicad_pcb --nets GND --plane-layers B.Cu
python3 py_router/route_diff.py board.kicad_pcb -O --nets "*_P" "*_N" --diff-pair-gap 0.15
python3 py_router/route.py board.kicad_pcb -O --nets "*" --power-nets GND --power-nets-widths 0.3The shared option groups β geometry, power-net widths, algorithm/strategy, proximity penalties, length/time matching, post-route DRC settings, and debug layers β apply across the routing CLIs and are documented in full in Configuration.
- Python 3.9+ (the router is built
abi3-py39whether it is downloaded or built from source, so building locally does not lower the floor β on 3.8 the module compiles and then fails to load withsymbol not found ... _PyCMethod_New) - numpy 1.22 or newer (
pip3 install "numpy>=1.22") β below 1.22 the stack fails with errors that name neither numpy nor this tool: scipy's "A NumPy version=1.22.4 ... is required" and
TypeError: 'numpy._DTypeMeta' object is not subscriptable - scipy (
pip3 install scipy) - used for optimal target assignment and Voronoi partitioning - shapely 2.0 or newer (
pip3 install "shapely>=2.0") - polygon operations: multi-net plane layers, the placement courtyard reader - Pillow (optional,
pip3 install Pillow; 10.1+ for full-size caption fonts) - board renders and the placement preview; without it only rendering is off python3 -m pip install -r requirements.txtinstalls the Python dependencies into the selected CLI interpreter.- Rust toolchain β only needed if you build the router from source (
python3 build_router.py --from-source); not required when using the prebuilt binary
- No push-and-shove (routes around obstacles, doesn't move them)
- Micro, blind and buried vias one span per route step:
route.py --via-span TOP BOTTOMlays vias that join only that run of copper layers and routes on those layers (Configuration);route_diff.py,bga_fanout.pyandqfn_fanout.pytake the same flag;repair_planes.pyand the route step's plane finalize lay their taps as vias of the span; one search does not choose between via types, androute_planes.py's stitch and thermal vias are through vias - No coarse grid assignment before detailed routing to plan overall topology
- Area-scoped design rules in part: a
.kicad_drurule conditioned on a rule area is honoured as a (net-filtered)disallowkeep-out, and a clearance or track-width rule whose condition is one area predicate, or an OR of them, is routed to inside the area (see Configuration); a rule with further condition terms is not routed to (the run reports it), and a diff pair that has to pass an area raising the clearance above its gap is built at the area's value for the run (disclosed per pair; one that need not pass it is kept out of it);check_drc.pygrades them by where each track, via and pad stands
The most valuable contribution is routing a board we haven't seen: run
/plan-pcb-routing on your own design (or any open-hardware board), grade
the result with check_drc.py + check_connected.py, and file an issue for
anything that breaks β ideally with a pointer to the board file. Fixes and
pull requests for open issues are just as welcome. See
CONTRIBUTING.md for the full guide.
MIT License



