konnect-codex

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

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.