akcli-kicad 0.22.0

AI-native schematic design, purpose-built for KiCad — a zero-dependency (pure-stdlib Python) CLI.

English · 繁體中文 · 简体中文 · 日本語

akcli is a zero-dependency Python CLI for AI-native schematic design on KiCad — a scriptable design loop that you or any AI agent can drive end to end (bundled plugins/skills ship for Claude Code, Codex, and OpenCode, but a shell is all it takes). Author a .kicad_sch from a JSON op-list, run ERC / design-review / BOM / schematic ↔ PCB checks, simulate on ngspice, and source real JLCPCB/LCSC parts. Existing Altium .SchDoc / .SchLib / .PcbDoc / .PcbLib designs import read-only — an on-ramp into the KiCad flow, which is where all development happens.

Install

Zero runtime dependencies; needs Python ≥ 3.11 (for stdlib tomllib). The distribution is akcli-kicad; the command is akcli:

pipx install akcli-kicad        # or: pip install akcli-kicad
akcli --version

# or run straight from a clone, no install
git clone https://github.com/tipoLi5890/akcli
./akcli/bin/akcli --help        # wrapper auto-selects a Python ≥ 3.11

Claude Code plugin (marketplace name akcli):

/plugin marketplace add tipoLi5890/akcli
/plugin install akcli@akcli

Codex plugin (same name akcli):

codex plugin marketplace add tipoLi5890/akcli   # or `add ./` from a clone
codex plugin install akcli@akcli

Full details, per-agent setup, and troubleshooting in INSTALL.md.

Quickstart

Scaffold a real KiCad project with a worked example, then read, check, and draw into it — straight from the shell:

akcli project new demo --example voltage-divider                  # .kicad_pro/.kicad_sch/.kicad_pcb/lib tables/ops.json
cd demo
akcli read  demo.kicad_sch --summary                              # normalized JSON, context-budgeted
akcli check demo.kicad_sch                                        # ERC-lite + power + BOM + connectivity + integrity
akcli draw  demo.kicad_sch --ops ops.json                         # dry-run: shows changes + net diff
akcli draw  demo.kicad_sch --ops ops.json --apply --strict-nets   # atomic write + verify + backup
akcli project check                                               # project-integrity findings (still 0)
akcli undo  demo.kicad_sch                                        # revert the last write

Every write is a dry run by default; --apply goes through an atomic snapshot → temp → verify → replace pipeline with a pure-Python connectivity gate, and akcli undo reverts from a rotated backup stack. Altium files are read-only offline.

What it does

One normalized model behind every command, so each check, diff, and report works on a KiCad .kicad_sch — and just the same on an imported Altium .SchDoc:

Two headline examples — a design review and a part search:

akcli review analyze board.kicad_sch --profile deep --pcb board.kicad_pcb   # advisory findings + evidence
akcli jlc search "0.1uF 0402 X7R"                                           # JLCPCB/LCSC catalog (needs network)

Use with AI agents

akcli is a plain CLI, so any shell-capable agent can drive it. Commands emit structured JSON with --json (carrying a version stamp — schema_version, or a family field like proposals_version / facts_version), each op-list carries a protocol_version, and akcli capabilities self-describes the entire CLI surface in one JSON document — and every error code ships a machine-readable remediation hint.

• Claude Code — install the bundled plugin for 8 /akcli:circuit-* commands (review, pinmap, draw, diff, parts, sim, datasheet, release) plus 13 skills spanning design, review, authoring, Altium interop, parts sourcing, calculators, and release gating.
• Codex — install the bundled plugin, or drop the loose skill folders into .agents/skills/ for auto-discovery. See docs/codex-plugin.md.
• OpenCode — auto-discovers the bundled skills; see INSTALL.md for the exact commands.

Why akcli

• Zero runtime dependencies. Standard library only (including tomllib) — easy to vendor, sandbox, or run in CI.
• Purpose-built for KiCad. An iterative KiCad S-expression parser and byte-stable writer at the core; Altium designs come in read-only through pure-stdlib OLE2/CFBF record decoding, straight into the same KiCad flow. No compiled extensions.
• Byte-identical re-apply. Deterministic UUIDv5 + replace-in-place makes every edit idempotent — re-running an op-list produces the same bytes.
• Connectivity is the only hard write gate. Every plan/draw prints a before/after net diff (splits, merges, renames — matched by pin membership, never by name); --strict-nets refuses a write that splits or merges a named net.
• Net inference you can trust. A rebuilt net layer handles global same-name merges, junctions, T-junctions, and No-ERC markers — fixing the classic "same-named nets split into single-pin nets" bug.

Optional external tools

"Zero-dependency" means zero Python package dependencies: pip install pulls in nothing, and the entire core loop (read / plan / draw / check / diff / calc / render) runs on the standard library alone. A few features can use something outside Python — always detected at runtime, never required by the core loop:

akcli doctor probes each of these and prints per-OS remediation.

Documentation

Roadmap

Shipped (v0.22.0): complete KiCad project scaffolding — project new / project init write the .kicad_pro, a blank .kicad_pcb board container, the project lib tables and a .gitignore around a root sheet (--example NAME drops in a worked op-list), while project info / project check read and gate what the project binds — KiCad write/draw from a 22-op + 10-macro vocabulary (hierarchical add_sheet, optionally creating the child sheet inside the same transaction with "create": true, writes into a child sheet of an existing hierarchy and across several sheets in one atomic transaction, a net-diff safety rail evaluated over the whole sheet tree, per-instance references on a reused sheet, new / multi-level undo / undo --run), net-preserving arrange --groups re-layout, the advisory akcli review engine (six detector families, now including power-entry protection, plus a datasheet facts store, propose / tree / validate), ERC / power / BOM / diff / pinmap / intent / contract checks with waivers (SARIF from check --format sarif / review report --format sarif), read-only document check --integrity, schematic ↔ PCB verify, a project library workspace, versioned fab profiles, a release preflight gate, akcli sim on KiCad's bundled ngspice, JLCPCB/LCSC sourcing with datasheet fetch, 60 standards-cited calculators, pure-stdlib SVG rendering that draws the real symbol artwork from KiCad lib_symbols, and version-tolerant Altium/KiCad readers. Standard symbol nicknames resolve on a stock KiCad install: the compiled-in ${KICAD*_SYMBOL_DIR} paths are derived from the located kicad-cli, and akcli doctor reports whether that resolution works here.

Ahead (→ v1.0): the contract-freeze audit. The first PyPI release (pip install akcli-kicad) shipped in 0.15.0. Deferred by decision: a GitHub Action gating schematic PRs, the view waveform panel, and a native MCP server (the plain CLI serves agents today). Full plan with exit criteria in ROADMAP.md.

Acknowledgments

akcli jlc builds on (full attribution in ACKNOWLEDGMENTS.md and THIRD_PARTY_NOTICES.md):

• JLC2KiCadLib by TousstNicolas (MIT) — LCSC → KiCad conversion core, vendored.
• jlcsearch (tscircuit, MIT) and jlcparts (MIT) — part-search backend.
• EasyEDA / LCSC / JLCPCB — component data source.

Contact

Questions, bugs, or feature requests: please open a GitHub issue.

License

MIT © 2026 Li, ching yu. See LICENSE; third-party attribution in ACKNOWLEDGMENTS.md and THIRD_PARTY_NOTICES.md, and the security model in SECURITY.md.