ki-stack-live

name	ki-stack-live
description	Control a running KiCad session through the official Python IPC bindings. Use when asked to inspect live board state, query a current selection, mutate a running board, automate editor actions, or write Python scripts that chain many IPC calls together.
license	MIT
compatibility	opencode
allowed-tools	["Bash","Read","Glob","Grep"]

ki-stack-live

Purpose

This skill teaches the agent how to use kicad-python as the main live action space for KiCad.

It is the canonical ki-stack skill for:

• connecting to a running KiCad instance
• inspecting open board state
• inspecting the current selection
• scripting multi-step live edits
• grouping changes into a single undoable commit
• saving, reverting, and exporting when appropriate

When to use it

Use this skill when the user asks to:

• automate a running KiCad board
• inspect or modify the current board or selection
• write Python that chains several IPC operations together
• interact with KiCad through code instead of through granular custom tools

Do not use this skill when:

• the task is purely offline file surgery
• the task is just rendering or checks
• no live KiCad session is needed and a deterministic file edit is simpler

Shared assumptions

• Prefer kicad-python for live state and live edits.
• Prefer Python snippets over ad hoc Rust snippets for IPC scripting.
• Prefer explicit commit sessions for multi-step edits.
• Prefer kicad-cli for rendering and checks even if the edit path was IPC.

Phase 1: Orient

1. Confirm the KiCad version:

   skills/ki-stack/bin/kicad-version
   

2. Probe Python bindings only:

   skills/ki-stack/bin/kicad-python-smoke
   

3. Probe a live connection if the task needs one:

   skills/ki-stack/bin/kicad-python-smoke connect
   

4. If connection fails, interpret it in a version-aware way:

• KiCad 9/10: likely no running GUI instance, API server disabled, or binding mismatch
• KiCad 11+: headless may be possible, but the environment may still be missing the socket or token

If live IPC is unavailable and the user only needs a structural edit, route to ki-stack-file-surgery instead.

Phase 2: Inspect

Start with the smallest script that proves the connection and retrieves relevant context.

Minimal baseline:

from kipy import KiCad

with KiCad() as k:
    print(k.get_version())
    board = k.get_board()
    print(board.name)
    print(len(board.get_nets()))
    print(len(board.get_footprints()))

Useful first reads:

• board.get_nets()
• board.get_tracks()
• board.get_vias()
• board.get_footprints()
• board.get_pads()
• board.get_zones()
• board.get_selection()
• board.get_selection_as_string()
• board.get_as_string()
• board.get_title_block_info()

If the request is selection-centric, inspect selection first before inventing search logic.

Common board task examples

Start from these copy-paste examples instead of writing from scratch every time:

• skills/ki-stack/examples/ipc/hello_kicad.py
• skills/ki-stack/examples/ipc/board_inventory.py
• skills/ki-stack/examples/ipc/layer_overview.py
• skills/ki-stack/examples/ipc/selection_dump.py
• skills/ki-stack/examples/ipc/update_title_block.py
• skills/ki-stack/examples/ipc/save_board_copy.py

Use the closest script, then modify it minimally.

Recommended progression for a new task:

1. run hello_kicad.py
2. run board_inventory.py
3. if selection matters, run selection_dump.py
4. copy the closest example into a task-specific script
5. verify with ki-stack-render and ki-stack-verify

Phase 3: Execute

For any edit with more than one mutation, use a commit session.

Canonical mutation pattern:

from kipy import KiCad

with KiCad() as k:
    board = k.get_board()
    commit = board.begin_commit()

    title = board.get_title_block_info()
    title.title = "Agent Edited Board"
    board.set_title_block_info(title)

    board.push_commit(commit, "Update board title")
    board.save()

If the script detects a problem or the result is clearly wrong:

board.drop_commit(commit)

Common live actions to teach and reuse:

• inspect state with get_* methods
• create items with create_items()
• update items with update_items()
• remove items with remove_items()
• regroup visual changes into one undo step with begin_commit() and push_commit()
• refill zones with refill_zones() when copper changes require it
• save with save() when the task calls for persistence

Phase 4: Verify

Live edits are not done when the IPC script exits. They are done when the result is proven.

Preferred verification loop:

1. save if needed
2. render the affected artifact with ki-stack-render
3. run DRC/ERC if the edit could affect electrical correctness
4. report the exact script and outputs used

For PCB edits, commonly verify with:

skills/ki-stack/bin/kicad-drc-json board.kicad_pcb drc.json

Phase 5: Report

Always report:

• whether IPC connection succeeded
• whether a live board was open
• what script was executed
• whether a commit was pushed or dropped
• what was saved
• what render/check evidence was produced

Good script shape

Write short, single-purpose Python scripts.

Preferred shape:

1. import KiCad
2. connect inside with KiCad() as k:
3. inspect just enough context
4. begin commit if editing
5. make the mutation
6. push or drop commit
7. save if needed
8. exit cleanly

Avoid sprawling one-off scripts with mixed concerns.

Helper assets

References:

• skills/ki-stack/references/ipc-recipes.md
• skills/ki-stack/references/ipc-board-workflows.md
• skills/ki-stack/references/version-matrix.md

Helpers:

• skills/ki-stack/bin/kicad-version
• skills/ki-stack/bin/kicad-python-smoke

Templates:

• skills/ki-stack/templates/python-ipc-script.py

Examples:

• skills/ki-stack/examples/ipc/hello_kicad.py
• skills/ki-stack/examples/ipc/board_inventory.py
• skills/ki-stack/examples/ipc/layer_overview.py
• skills/ki-stack/examples/ipc/selection_dump.py
• skills/ki-stack/examples/ipc/update_title_block.py
• skills/ki-stack/examples/ipc/save_board_copy.py

Guardrails

• If IPC is unavailable, do not pretend the script ran. Report BLOCKED or route to file surgery.
• If the task is multi-step, use commit sessions.
• If the script writes to the board, verify with render or checks before claiming success.
• If KiCad returns busy or timeout states, retry a small number of times and then report the condition explicitly.
• If the task is naturally offline and deterministic, do not force IPC use.

Completion states

• DONE: live script executed and the result was verified
• DONE_WITH_CONCERNS: script executed but verification is partial or version-dependent
• BLOCKED: Python bindings or IPC connection unavailable, or live board access failed irrecoverably
• NEEDS_CONTEXT: no board is open, target object is unclear, or the intended mutation is underspecified