KiVi turns the KiCad projects in your GitHub and GitLab repositories, or on
your disk, into something you can actually look at. Any source control forge shows a changed
.kicad_pcb as thousands of lines of S-expressions; reviewing it usually
means checking out both versions and flipping between KiCad windows. In KiVi,
schematics, boards and 3D views open in seconds, a visual diff tells you what
changed in KiCad terms, and comments pinned to parts and nets make a board
change as easy to review as a code change.
- Nothing to set up on a server. GitHub or GitLab stays your source control, diff and review system; KiVi is a desktop app that parses and renders everything locally.
- Nothing to install. One
.AppImageon Linux, one.exeon Windows, one.dmgon macOS. - No account needed to play around. Public repositories work signed out; sign in to GitHub or GitLab (one at a time) for private repositories and the full review features.
- You are in control of access. GitHub sign-in uses a GitHub App with fine-grained permissions, and you choose which repositories it can read; GitLab sign-in uses an OAuth application.
- KiCad 6 to 10. Tested against the demo projects that ship with KiCad 10.
Screenshots show CM5 MINIMA REV3 by Pierluigi Colangeli (CERN-OHL-S-2.0), from KiCad's demo projects. The changes, review comments and issues in them were made up for these examples.
🗂 Every project at a glance. KiVi finds every KiCad project in the repositories you can reach and in folders you add, and shows each as a card with a rendered board thumbnail. One click opens its schematic, PCB, 3D view or BOM.
🔍 Viewing, cross-probing and more. Click a symbol to see its fields and every pin with its net, or a wire to select the whole net. Highlight on PCB shows that net on the board, with its length, layers and vias; Show in 3D lights it up and turns the camera to the side it's routed on. Switch PCB layers one by one, flip to the bottom, and measure between pads, vias and model corners (key M).
🧮 A diff that speaks KiCad. Compare a pull request, a commit, two branches, or your uncommitted local work. KiVi lists changes the way a designer thinks about them and marks each one on both versions side by side:
- Schematic: which pins joined or left each net; parts added, removed or edited; library symbols whose pinout, pin types or body changed, with every part that uses them.
- Board: parts moved, rotated, flipped or re-wired; what changed inside a footprint (pads, drills, mask and paste overrides, 3D models, silkscreen); routing, vias, zones, outline and stackup.
- Design rules: a table of what changed in the
.kicad_proand.kicad_dru. - Not a change: redrawn wires that connect the same pins, re-annotation, refilled zones, or the pads of a part that merely moved.
Here a footprint was updated from a corrected library: four pads got longer, pad 1 got a solder mask override, the 3D model went from VRML to STEP and a pin-1 mark was added to the silkscreen.
And here the LED symbol's anode and cathode were swapped in the library: KiVi reports it once, with both LEDs that use it and the nets that changed.
💬 Review where the problem is. Press C and click a footprint, pad, net or symbol to comment on it. Comments are ordinary pull request review comments on GitHub (discussions on a merge request's file on GitLab), so your team sees them there too, and they stay pinned to the part across later pushes. Outside a pull request the same pin opens an issue: a hardware change request that a later pull request can close (see how).
🌿 Git without the git. Download a project, make a branch, edit in KiCad (KiVi reloads as you save), then commit, push and open a pull or merge request from one menu, with git built in. KiCad files don't merge reliably as text, so KiVi never merges a file both sides changed; it keeps your work safe on a branch instead.
🔗 Works with your KiCad. Link your KiCad installation and KiVi loads 3D models from your library exactly as KiCad does, and Open in KiCad opens the project in one click.
KiVi gives a team two ways to talk about a design, both pinned to the part, pad or net they're about and both stored on GitHub (or GitLab: there a pull request is a merge request, a review comment a file discussion), so nothing lives only in KiVi:
| Review comment | Change request | |
|---|---|---|
| For | Discussing a proposed change before it's merged | Asking for a change to the design as it is |
| Made in | A pull request: its visual diff, or the viewer at its head (Hardware) | A branch of a GitHub or GitLab project, or a local copy linked to one |
| How | Press C (Comment) and click | Press C (Request change), click, give it a title |
| On GitHub it's | A review comment on the .kicad_sch / .kicad_pcb file, in the pull request's conversation and Files changed |
An issue labelled kivi, in the repository's Issues |
| On GitLab it's | A discussion on that file of the merge request, in its Overview and Changes | An issue labelled kivi, in the project's Issues |
| Done when | Resolved, in KiVi or on the forge | Closed; a pull request whose description says "Fixes #N" ("Closes #N" on GitLab) closes it when merged |
| Listed in | The pull request's side panel | The schematic and PCB side panels, KiVi's home Issues view, the forge |
| Pins | Numbered 1, 2, 3… in orange | Issue numbers (#12) in green |
-
Find it. The home screen's pull request view lists the open pull requests in your projects, each saying how many KiCad files it changes. Visual diff opens it; Hardware opens the viewer at its head.
-
Review it. Go through the change list; each item zooms to the change on both versions. Press C, click what you have a question about and write it: here a question about U405's longer pads, pinned to U405. The author answers and resolves it in KiVi or on github.com, where it's an ordinary review comment. The repository's open change requests show up too, in green, since the pull request may be what fixes them.
-
Pin a request to the hardware. In the viewer on any branch, press C, click the part, pad or net, and give the request a title: here #12 asks to move the HDMI connector J501, and has a reply underneath. Anyone with access to the repository sees it in KiVi or in the repository's Issues on GitHub or GitLab.
-
Keep track of them. The home screen's Issues view gathers the open change requests of all your projects, each saying what it's pinned to; Hardware opens it right there.
-
Fix it in a pull request. The pull request that drills M701 bigger says "Fixes #9" in its description, so in its visual diff issue #9 is marked closes with this PR: the reviewer sees the request next to the change that answers it, and GitHub closes the issue when the pull request is merged. For the other issues, Close with this PR adds the "Fixes #N" line for you (signed in). GitLab works the same, with merge requests and "Closes #N".
- Get KiVi. Download it from the
Releases page: on Linux the
AppImage (
chmod +x KiVi_*.AppImage, then run it); on WindowsKiVi_<version>_x64.exe(run it; it isn't code-signed yet, so SmartScreen asks once: More info → Run anyway); on macOSKiVi_<version>_universal.dmg(drag KiVi to Applications; it isn't notarised yet, so the first time it's blocked: System Settings → Privacy & Security → Open Anyway). Or build it yourself. - Add a public project. In Projects, click + → Remote
project… and enter
greatscottgadgets/hackrf(the HackRF One software defined radio, on GitHub),https://gitlab.com/riglol/lapod(LVDS breakout boards, on GitLab), or any public repository with KiCad projects. No sign-in needed. - Look around. Open its card: click parts in the schematic, cross-probe to the PCB, measure something, spin it in 3D.
- See what changed. Open History in the project bar, pick a commit that touched the hardware and press Visual diff. In your own repositories, the pull request icon in the header lists the open pull (or merge) requests the same way.
- Bring your own. + → Local project… adds a folder from your computer. Edit it in KiCad, save, and press Visual diff to see your uncommitted changes the way a reviewer would.
- Sign in (account menu, top right, then GitHub or GitLab) to see your private repositories and the pull requests waiting for your review, and to comment. KiVi is signed in to one of them at a time.
KiVi is young and we'd love to hear how it does on your projects: boards it draws wrong, diffs that miss a change or report noise, anything confusing. Open an issue with the KiCad version and, if you can, the file. Good to know before you start:
- Linux is where it's used day to day. The Windows build is made by CI and hasn't been tried much by hand. The macOS build has been tried by hand on Apple Silicon (macOS 27, KiCad 10.0.1: viewer, 3D with the linked KiCad's models, Open in KiCad, GitHub sign-in); not yet on Intel.
- See Known limitations for what KiVi doesn't do yet.
The user guide covers every feature in detail: Projects · Schematic, PCB and 3D · Visual diff · Pull requests · Review comments on pull requests · Change requests as issues · Local copies, branches and pushing · Linking KiCad · Signing in to GitHub and GitLab · Links into the viewer · How the gallery stays fast.
- 3D models embedded in KiCad 9+ files (
kicad-embed://…) aren't read yet; such parts show without a model unless a file with the same name is in the repository. - KiCad 9 padstacks (different pad shapes on inner layers) are drawn with the outer layers' shape.
- Text uses a regular sans font scaled to KiCad's metrics instead of KiCad's stroke font (the newstroke font data is GPL-2.0, so it is not bundled). Layout and anchoring match, but glyph shapes differ.
- Schematic nets are traced per sheet (wires, junctions, labels, pins) and mapped to board nets through component pins; the name shown is the board's when there is one. Buses aren't traced, and the diff doesn't follow a net through a global label on another sheet.
- The default 3D model source is the KiCad 6-era GitHub mirror of
kicad-packages3D; models added in later KiCad versions need KiCad linked in Settings or another model source. A GitHub repository model source is listed once through the API, so it counts against the rate limit. The first view of a board with many STEP models is slow (KiCad 10's library is STEP only); later views use the cache. - Git LFS files aren't fetched from GitHub (GitLab returns their content).
- GitLab: gitlab.com only (no self-hosted servers yet). Signed out, GitLab shows no merge request comments and no issue comments, and limits requests from your network tightly; a big repository is listed 100 files per request.
- A file changed on both sides is never merged (on purpose: KiCad files don't merge reliably as text); Pull offers to move your commits to a new branch instead.
- The tokens and refresh tokens are kept in the app's local storage; a release should keep them in the OS keychain, at least the long-lived refresh token.
- Auto-update, code signing, notarisation, file associations.
# once: system libraries and Rust (Linux)
sudo apt install libwebkit2gtk-4.1-dev libxdo-dev libayatana-appindicator3-dev librsvg2-dev build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install tauri-cli --version "^2" --locked
cargo tauri dev # run from source
cargo tauri build # release binary + AppImage in src-tauri/target/release/bundle/appimage/KiVi is a Tauri 2 app. Windows builds the same way, with
Rust and Python installed: cargo tauri build --no-bundle makes
src-tauri/target/release/kivi-desktop.exe, which runs as it is, with the
pages built in (plain cargo tauri build also makes an NSIS installer, set in
src-tauri/tauri.windows.conf.json, which Tauri merges on Windows).
On macOS, install the Xcode Command Line Tools (xcode-select --install,
which bring python3) and Rust; no other libraries are needed (Tauri uses
the system's WKWebView). cargo tauri build makes
src-tauri/target/release/bundle/dmg/KiVi_<version>_aarch64.dmg (set in
src-tauri/tauri.macos.conf.json, which Tauri merges on macOS); CI builds one
for both architectures with rustup target add x86_64-apple-darwin and
cargo tauri build --target universal-apple-darwin. If the build stops with
hdiutil: couldn't unmount … Resource busy, run it as
CI=true cargo tauri build: that skips the Finder window styling of the disk
image, which can keep it busy. Tauri doesn't cross-compile. The pages
are plain ES modules with no build step; tools/build_web.py (run by Tauri)
copies them to dist/web.
Settings and sign-in are kept per user (%LOCALAPPDATA%\app.kivi.desktop on
Windows, ~/.local/share/app.kivi.desktop on Linux,
~/Library/WebKit/app.kivi.desktop on macOS), not next to the program.
The Windows .exe needs the WebView2 runtime, which is part of Windows 11 and
comes with Edge updates on Windows 10 (otherwise get the Evergreen runtime
from Microsoft).
To build in your own GitHub App, set KIVI_GITHUB_CLIENT_ID and
KIVI_GITHUB_APP_SLUG when building, and for GitLab your gitlab.com OAuth
application's ID as KIVI_GITLAB_CLIENT_ID (in CI: the repository variables
of the same names, under Settings → Secrets and variables → Actions →
Variables); without them the sign-in dialog asks for them. GitHub's
device-flow endpoints don't send CORS headers, so sign-in requests run in Rust
(oauth_post in src-tauri/src/lib.rs, for both forges).
index.html viewer
diff.html visual diff
inbox.html home screen (projects, pull requests, issues)
src/sexpr.js S-expression parser (+ tree helpers)
src/geom.js matrices, arcs, bounding boxes
src/text.js text layout (KiCad metrics, markup, escapes)
src/drawing-sheet.js .kicad_wks parser/renderer, built-in default sheet
src/project.js project discovery, hierarchy walk, page numbering
src/forge/ code hosts: the forge interface (index.js) and one adapter
per forge (github.js, gitlab.js: every API request,
comparisons, review comments, issues, lists, sign-in
details, web links)
src/sources.js text before a patch, 3D model path resolution
src/diff/ semantic schematic, net, board and design rule diffs, comment anchors
src/review.js comment markers and the thread shape (review comments and
change requests), the same on every forge
src/sch/ schematic model, renderer, themes
src/pcb/ board model, renderer, shapes, hit testing,
outline extraction, face textures, three.js scene,
STEP conversion (worker) and its cache, measuring
src/app/ UI: tabs, pan/zoom viewport, inspectors, BOM, diff page,
branch and history menus, measuring
src/desktop/
tauri.js TauriSource (folder on disk), GitRevSource (it at a commit), drag and drop, link routing,
folder chooser, sign-in (forge chooser, device flow), token refresh
desktop.js additions to the viewer and diff pages
account.js header on every page: home icons, account menu, Settings dialog
inbox.js, desktop.css home screen: view switch, pull/merge requests, issues
card-zoom.js Ctrl + wheel resizes the gallery's cards
projects.js project gallery: repository scan, caches, cards
thumb-worker.js board thumbnails (parse + render off the main thread)
git.js local copies: download/link, branch and history menus, commit, push, pull
add-project.js the "+" menu: local project, remote project (settings `watchRepos`)
local-projects.js local project folders in the gallery, Link to remote…
icons.js header and menu icons (repository / pull request follow Octicons)
src-tauri/ Rust app
src/lib.rs commands: open_folder, list_folder, read_file, startup_folder,
model folders, forge_build_config, oauth_post (sign-in)
src/picker.rs the folder chooser through the desktop portal (Linux)
src/git.rs git commands (clone, branch, local changes, commit, push, pull, fetch with prune),
GitHub and GitLab remotes (tokens only to their hosts)
src/git_http.rs git over HTTPS through reqwest (no OpenSSL)
src/kicad.rs linking KiCad (program, version, path variables), Open in KiCad
tauri.conf.json window, CSP, bundle targets
capabilities/ which plugin APIs the page may call
icons/ app icons (tools/make_icons.py)
vendor/ three.js 0.169, occt-import-js (LGPL-2.1), see vendor/README.md
tests/ headless checks (gjs), Tauri API mock
tools/ build, CLI rendering, visual comparison, icons, headless browser,
screenshot preludes
assets/ logo (SVG)
docs/README.md user guide (every feature in detail)
docs/screenshots/ README images
The parsers, renderers and diff engines have no DOM dependency, so they run in a page, a worker, or headless.
assets/kivi-logo.svg is the logo. The page headers show it in the header's
colours (src/app/logo.js inlines it: the orange parts follow the brand colour,
the white ones the header background). The app icons in src-tauri/icons/ are
generated from it:
python3 tools/make_icons.pyThe tooling runs on gjs (GNOME's JavaScript runtime), so Node is not needed.
The tests use KiCad's demo projects without a KiCad installation:
tests/kicad-demos.txt lists the design files they read (172 files, 74 MB, at a
pinned KiCad release, with git hashes), and tools/fetch_demos.py downloads
those from KiCad's GitHub mirror into the git-ignored tests/kicad-demos/,
checking each hash and skipping files already there.
python3 tools/fetch_demos.py # get / verify the listed files
python3 tools/fetch_demos.py --refresh 10.0.7 # move the list to another KiCad release
# Parse and render every KiCad demo project, check invariants
# (envelope, NaN, unresolved references, pin-to-wire connectivity, footprints)
gjs -m tests/run.js # or: gjs -m tests/run.js path/to/projects …
gjs -m tests/diff.js # schematic, library symbol, board, footprint and rules diffs
gjs -m tests/nets.js
gjs -m tests/review.js
gjs -m tests/gitlab.js
gjs -m tests/models.js
cargo test --manifest-path src-tauri/Cargo.toml --lib # Rust side: model folders, git (needs dist/web: run tools/build_web.py once)
# Render a file to SVG
gjs -m tools/render.js board.kicad_pcb out.svg --layers F.Cu,F.SilkS,Edge.Cuts
gjs -m tools/render.js board.kicad_pcb face.svg --face front # 3D texture artwork
# Optional, manual, needs KiCad installed: compare against KiCad's own export
kicad-cli sch export svg -o ref/ project.kicad_sch
python3 tools/compare.py ref/project.svg out.svg cmp.png x0 y0 x1 y1 [px_per_mm]
# Smoke test: every page loads without script errors, the viewer opens
# pic_programmer (headless WebKit, Tauri API mocked, no network)
tests/smoke.sh
# Drive the pages yourself (served over HTTP, Tauri API mocked)
python3 -m http.server 8000 &
LIBGL_ALWAYS_SOFTWARE=1 xvfb-run -a gjs -m tools/browser-check.js \
"http://127.0.0.1:8000/inbox.html#projects" shot.png \
--prelude "$(cat tests/tauri-mock.js)" --wait "document.querySelector('.project-card')"tools/screenshots.sh regenerates every screenshot in this README (all, or
by name: tools/screenshots.sh viewer-3d-net) after a UI change. It needs no
network or sign-in: tools/screenshots-prelude.js answers GitHub and the
desktop app from the KiCad demo files, with a pull request that applies a few
fixes to the CM5 MINIMA board, and serves KiCad's installed 3D library
(KICAD3D, default /usr/share/kicad/3dmodels).
What a passing run prints:
$ python3 tools/fetch_demos.py # here 5 files were missing or damaged
downloading 5 of 172 KiCad 10.0.6 demo files from KiCad/kicad-source-mirror …
1.3 MB in 3 s
tests/kicad-demos: 172 KiCad 10.0.6 demo files ready
$ gjs -m tests/diff.js | tail -1
all diff checks passed
$ tests/smoke.sh
ok home
ok pull-requests
ok viewer
ok diff.github/workflows/ci.yml runs the tests on every pull request and push to
main (or master), and builds only for releases and manual runs:
- Tests: installs gjs, WebKitGTK and xvfb, restores the KiCad demo files
from the Actions cache (keyed on
tests/kicad-demos.txt, so they're downloaded only when the list changes or the cache expired after 7 unused days), then runs the unit tests, the full demo sweep andtests/smoke.sh. - Rust tests, alongside:
cargo teston the Rust side, with the Rust build cached, and a check thatTHIRD-PARTY-NOTICES.mdis up to date. All three builds below wait for both test jobs. - Build (Linux), only for tags and manual runs (Run workflow on the
Actions tab):
cargo tauri build, with the Rust build and the Tauri CLI cached; lists the AppImage's bundled system libraries inappimage-libraries.md. The AppImage and that list are thekivi-linuxartifact. - Build (Windows), likewise:
cargo tauri build --no-bundleon a Windows runner; thekivi-windowsartifact holdsKiVi_<version>_x64.exewithLICENSEandTHIRD-PARTY-NOTICES.mdnext to it (GitHub zips every run artifact for download; release files aren't). - Build (macOS), likewise:
cargo tauri build --target universal-apple-darwinon a macOS runner; thekivi-macosartifact holdsKiVi_<version>_universal.dmg(Apple Silicon and Intel;LICENSEandTHIRD-PARTY-NOTICES.mdare inside the app). Not code-signed or notarised.
Pushing a tag v<version> (for example v0.2.0) runs all five and publishes a
GitHub Release. The version comes from the tag: each build first runs
tools/set_version.py, which writes it into src-tauri/tauri.conf.json,
src-tauri/Cargo.toml and src-tauri/Cargo.lock, so there's nothing to bump
by hand (the versions in the repository are only for local and manual builds;
a tag that isn't v<major>.<minor>.<patch>, optionally with -beta.1 and the
like, fails the build). The release has the AppImage, the
Windows .exe, the macOS .dmg, LICENSE, THIRD-PARTY-NOTICES.md,
appimage-libraries.md and KiVi_<version>_source.tar.gz (git archive of
the tag, with the version written in). Merges don't build, so run the workflow by hand on main before
tagging and check all three builds pass.
KiVi is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3 or (at your option) any later version. It comes with no warranty.
It includes third-party software under its own licences: three.js (MIT),
Chevrotain (Apache-2.0), occt-import-js with Open CASCADE Technology (LGPL-2.1)
and the Rust crates behind Tauri (mostly MIT and Apache-2.0), plus three icons
from GitHub's Octicons (MIT) and KiCad's default drawing sheet (GPL-2.0-or-later).
THIRD-PARTY-NOTICES.md has their licence texts and is
installed with the app. Each release also carries its source code
(KiVi_<version>_source.tar.gz). Regenerate it with python3 tools/notices.py after
changing Cargo.lock or vendor/ (CI fails if it's out of date). The AppImage
also bundles system libraries (GTK, WebKitGTK, GStreamer…) from the build
machine; each release lists them with their licences and sources in
appimage-libraries.md.
The GitHub and GitLab logos in the sign-in dialog aren't part of KiVi: they're loaded from GitHub and GitLab when the dialog opens (GitLab's artwork is licensed CC BY-NC-SA, which isn't GPL-compatible, so KiVi doesn't ship it). GitHub is a trademark of GitHub, Inc. and GITLAB is a trademark of GitLab Inc.; KiVi isn't affiliated with either.













