Konnect Codex Plugin

A reviewed, versioned, first-class Codex plugin for Konnect.

konnect-codex is a standalone Codex plugin for the Konnect server. It
packages reviewed Codex-native skills, agents, hooks, and MCP configuration so
Konnect behaves like a first-class Codex integration. It is deliberately
separate from Konnect so each release can preserve a known-good Codex workflow
without changing Konnect itself.

Release numbers identify the Konnect release reviewed by the plugin:
konnect-codex v0.12.1 supports Konnect v0.12.1. A later -codex.N
suffix identifies a companion-only revision for that unchanged upstream release.
The exact reviewed upstream
commit and guidance fingerprints are recorded in
compatibility.json.

The plugin supplies:

• nine independently reviewed domain/workflow skills plus the execution router,
  including dedicated workflow selection, BOM qualification, and lifecycle
  guidance;
• a Codex execution-router skill that makes the eager-tool profile and safe
  KiCad workflow explicit;
• a discoverable multi-stage workflow catalog
  for custom parts, schematic construction, PCB transfer, placement, routing,
  recovery, review, manufacturing, and bring-up;
• five reviewed Codex agents for custom libraries, schematic construction, PCB
  layout, independent design review, and firmware/bring-up handoff, without a
  hard-coded model;
• a Freerouting-first PCB workflow that capability-tests Konnect's native
  DSN/MCP/SES path and retains a non-overwriting KiCad-native compatibility
  route with placement, route-import, and direct DRC acceptance gates;
• Codex-native hooks, relevant-prompt guidance, and a live-KiCad IPC fallback;
• a private Konnect configuration with eager_toolsets = true so clients that
  cache the first MCP tool list can see the complete tool catalogue;
• ownership, health checks, disable/enable, and exact uninstall support;
• a machine-enforced guidance change policy with
  per-file upstream provenance, named Codex enhancements, retirement rules,
  a living delta register, and explicit
  guidance standards.

The reviewed plugin skills are authoritative by default. Do not run
konnect init --client codex; that installs another set of skills with the same
names. If they are already installed, remove only that native guidance with
konnect uninstall --client codex before syncing the plugin. An explicit
--prefer-native-skills option remains available for future compatibility
testing.

Upstream and credit

_{Original Konnect artwork; displayed here with credit to the upstream project.}

Konnect is created and maintained by
mixelpixx. Konnect provides the KiCad MCP server,
tool catalogue, file-safety model, and original hardware workflows on which
this plugin depends. konnect-codex is an independent Codex plugin and
does not replace or claim authorship of Konnect. Please report server and KiCad
tool issues to the upstream project and support its development there.

Community and support

Join the Konnect Discord community for
installation help, Codex and other AI-client setup, KiCad workflow discussion,
project showcases, and contributor coordination. GitHub remains the source of
truth for tracked work:

• Konnect server, IPC, KiCad, and core-tool defects:
  mixelpixx/Konnect issues
• Codex companion installation, guidance, lifecycle, and packaging defects:
  neusse/konnect-codex issues

Install with Codex

Open a Codex task and paste the following request. Codex can select the correct
release for the current operating system, verify it, install the plugin, and
run its health check for you:

Install the konnect-codex v0.12.1-codex.2 companion plugin from
https://github.com/neusse/konnect-codex/releases/tag/v0.12.1-codex.2 for this operating
system. First locate the Konnect executable and run `konnect --version`. Stop
without changing anything if Konnect is missing or is not exactly v0.12.1.
Download SHA256SUMS.txt and verify the plugin archive before extracting it.
Install the konnect-codex executable in a user-writable location on PATH. Do
not run `konnect init --client codex`. If Konnect's native Codex guidance is
already installed, remove only that guidance with `konnect uninstall --client
codex`. Preserve the Konnect server and its configuration. Run
`konnect-codex sync`, then `konnect-codex doctor`. Report the installed paths
and health result, and tell me when to start a new Codex task.

The installer registers konnect-codex@personal through Codex's plugin system.
Start a new Codex task after installation so Codex discovers the plugin's
skills, agents, hooks, and MCP server.

sync runs konnect --version before creating or replacing any plugin file.
Missing Konnect and every version other than the exact supported release stop
installation with a corrective error; existing plugin state is left unchanged.

Manual installation

Install the matching Konnect release normally, without its Codex guidance flag.
Then download the archive for your operating system from
GitHub Releases, put
konnect-codex on PATH, and run:

konnect --version            # must report: konnect 0.12.1
konnect-codex sync
konnect-codex doctor

You can also install the version-matched source release with Cargo:

cargo install --git https://github.com/neusse/konnect-codex --tag v0.12.1-codex.2
konnect-codex sync
konnect-codex doctor

Or install from a local checkout:

cargo install --path .
konnect-codex sync --konnect C:\path\to\konnect.exe --config C:\path\to\konnect.toml
konnect-codex doctor

sync installs the reviewed assets embedded in this release; it does not
translate files from ~/.claude. Passing --source <path> asks it to verify
that a Konnect checkout or installed asset directory still matches the reviewed
fingerprint before installation.

Codex requires the user to review and trust newly installed plugin hooks before
it runs them.

Lifecycle

konnect-codex disable       # remove active plugin and agents, retain generated state
konnect-codex enable        # reactivate the retained integration
konnect-codex audit         # verify installed Claude-side assets still match this release
konnect-codex native-status # compare native Konnect coverage with the plugin
konnect-codex sessions      # list active companion -> Konnect MCP process pairs
konnect-codex stop-sessions # retire those pairs before an upgrade or after a stale task
konnect-codex pcb-preflight --board C:\path\board.kicad_pcb --mode live
konnect-codex freerouting status # verify the compatibility route prerequisites
konnect-codex uninstall     # remove only plugin-owned files and marketplace entry

For a complete-board route, first test Konnect's native MCP sequence on the
actual board: check_freerouting, export_specctra_dsn,
route_specctra_dsn, plan_specctra_ses_import, then
apply_specctra_ses. Konnect v0.12.1's Rust exporter still rejects common legal
geometry including roundrect and unnumbered NPTH pads. For those boards, close
PCB Editor and use konnect-codex freerouting route --board <path>, which uses
KiCad's own DSN/SES APIs and writes a separate routed board. Both paths require
inventory, unrouted, short, visual, physics, and direct DRC acceptance.

uninstall verifies hashes before removing anything. If a managed file was
edited after installation, it stops and preserves the file. --force is
available only for intentionally discarding those plugin-owned edits.

Konnect v0.12.1 keeps MCP startup non-mutating; native guidance is installed
only by explicit konnect init. The companion therefore no longer creates or
repairs ~/.konnect/.installed-codex. The first real v0.11 sync removes the
legacy suppression guard and removes that marker only when an older companion
recorded that it originally created it. Native skill files remain untouched.

Each MCP launch owns its Konnect child process with an operating-system cleanup
boundary on Windows. If Codex retains obsolete MCP connections, sessions
shows the exact adapter/server PIDs and their owning process. stop-sessions
only stops a konnect.exe process whose direct parent is
konnect-codex.exe, then lets the waiting adapter exit normally; it does not
target Cargo, Rust, KiCad, standalone Konnect runs, or unrelated processes.
Run it before replacing either executable when an upgrade reports a locked
file. Codex starts a fresh session the next time the MCP server is needed.

Generated locations

• Plugin source: ~/plugins/konnect-codex
• Codex agents: ~/.codex/agents/konnect_*.toml
• State/config: ~/.konnect/codex-companion
• Marketplace entry: ~/.agents/plugins/marketplace.json

The plugin is installed as konnect-codex@personal using the Codex CLI. Native
Konnect skills under ~/.agents/skills are neither replaced nor removed; use
Konnect's client-scoped uninstall command if you previously installed them.

Release review process

Every Konnect release is handled as a compatibility review under the
guidance change policy:

1. Compare the new per-file upstream baseline with the previous release and
   account for every changed skill, reference, agent, hook, and tool contract.
2. Review every entry in policy/enhancements.json:
   port it, adapt it, or retire it only after its recorded condition is met.
3. Review every row in the living
   docs/GUIDANCE_DELTA_REGISTER.md and audit
   all runtime assets against
   docs/GUIDANCE_STANDARDS.md.
4. Run konnect-codex audit --source <Konnect checkout> against the pinned
   version, commit, per-file baseline, aggregate guidance, and hook fingerprint.
5. Validate enhancement assertions, reference reachability, hook target/runtime
   classification, skill frontmatter, agent TOML, lifecycle
   safety, tests, Clippy, and packaging on Windows, Linux, and macOS.
6. Run the end-to-end KiCad benchmark before publishing matching artifacts.
   Preserve its gate-by-gate ledger, failures, recovery, final artifact
   inventory, cleanup result, and terminal verdict in the benchmark project.