akcli-kicad 0.15.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

Read a design, check it, and draw into it — straight from the shell:

akcli read  board.kicad_sch --summary                            # normalized JSON, context-budgeted
akcli check board.kicad_sch                                      # ERC-lite + power + BOM + connectivity
akcli draw  board.kicad_sch --ops ops.json                       # dry-run: shows changes + net diff
akcli draw  board.kicad_sch --ops ops.json --apply --strict-nets # atomic write + verify + backup
akcli undo  board.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 schema_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 five /akcli:circuit-* commands (review, pinmap, draw, diff, parts) plus twelve 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.15.0): KiCad write/draw from a 22-op + 10-macro vocabulary (hierarchical add_sheet, net-diff safety rails, new / multi-level undo), 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 and SARIF, 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, and version-tolerant Altium/KiCad readers.

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.