Document Codex's Plugins panel, confirmed working with no session gotcha

Codex's own Plugins panel (Add plugin marketplace, Source PyDevices/mpftp)
reads the same .claude-plugin/marketplace.json + plugin.json + .mcp.json +
skill this repo already ships for Claude Code -- no separate Codex plugin
package needed. Confirmed end to end: connected a real board, listed its
filesystem. Unlike the Claude Desktop app, Codex showed no "Local session
required" restriction -- it just worked in a normal chat.

codex/README.md now documents both real paths: the Plugins panel (GUI) and
the bare codex mcp add / config.toml route for headless CLI use.

Author: bdbarnett

integrations/README.md

@@ -8,30 +8,36 @@ and firmware build/flash. None of them reimplement any of that; they only
 wire an agent host up to the server and, for Claude Code, add condensed
 board-workflow guidance as a skill.
 
-| | Claude Code (CLI) | Claude Desktop app | Codex CLI |
-|---|---|---|---|
-| Directory | [`claude-code-plugin/`](claude-code-plugin/) | [`claude-desktop-extension/`](claude-desktop-extension/) | [`codex/`](codex/) |
-| Distribution | Installable plugin (`.claude-plugin/plugin.json`, `.mcp.json`, a skill) | MCPB extension (`manifest.json`), installed unpacked | No plugin system — a `~/.codex/config.toml` snippet |
-| Board-workflow guidance | Bundled skill (`skills/board-tools/SKILL.md`) | None yet — MCPB extensions don't carry skills | Point `AGENTS.md` at `docs/agent-guide.md` |
+| | Claude Code (CLI) | Claude Desktop app | Codex (app, Plugins panel) | Codex (bare CLI) |
+|---|---|---|---|---|
+| Directory | [`claude-code-plugin/`](claude-code-plugin/) | [`claude-desktop-extension/`](claude-desktop-extension/) | same as Claude Code — [`claude-code-plugin/`](claude-code-plugin/) | [`codex/`](codex/) |
+| Distribution | Installable plugin (`.claude-plugin/plugin.json`, `.mcp.json`, a skill) | MCPB extension (`manifest.json`), installed unpacked | **Same marketplace/plugin format as Claude Code** — Codex's Plugins panel reads it directly, no separate package | No plugin system — a `~/.codex/config.toml` snippet |
+| Board-workflow guidance | Bundled skill (`skills/board-tools/SKILL.md`) | None yet — MCPB extensions don't carry skills | Bundled skill (same one) | Point `AGENTS.md` at `docs/agent-guide.md` |
+| "Local session" gotcha | Yes — see below | Yes — see below | **No** — confirmed working in a normal Codex chat | N/A |
 
-**These are three different products** and none of the three install paths
-covers the other two — a plain `claude` CLI session (with `/plugin` support)
-is not the same thing as the Claude Desktop app (Settings → Extensions), and
-neither is Codex. Confirm which one you're actually looking at before
-picking a directory.
+**These are (at least) four different install paths across two products**,
+and confirmed working end to end in all four as of 2026-08-24. A plain
+`claude` CLI session (with `/plugin` support) is not the same thing as the
+Claude Desktop app (Settings → Extensions), which is not the same thing as
+either Codex path. Confirm which one you're actually looking at before
+picking a directory — though note Claude Code's plugin and Codex's Plugins
+panel happen to consume the exact same files, so
+[`claude-code-plugin/`](claude-code-plugin/) genuinely serves both.
 
 Requires `pydevices-mpftp` installed (`pip install pydevices-mpftp`) — all
-three run its `mpftp-mcp` console script.
+of them run its `mpftp-mcp` console script.
 
-**Both Claude-branded integrations need a "Local" session.** In the Claude
-Desktop app, MCP tools from a plugin or extension only attach to chats
-started as a **Local** session — confirmed by testing that a **Cloud** or
-even a **WSL** session shows the install as complete and "Connected" but
-exposes no tools at all, silently. Check the session-type picker
-(Local/Cloud/Remote Control/WSL/SSH, wherever new chats/tasks get created)
-before assuming a broken install. See the "Local session required"
-sections in [`claude-code-plugin/README.md`](claude-code-plugin/README.md)
-and [`claude-desktop-extension/README.md`](claude-desktop-extension/README.md)
+**The two Claude Desktop app paths need a "Local" session; Codex doesn't
+have this restriction.** In the Claude Desktop app, MCP tools from a
+plugin or extension only attach to chats started as a **Local** session —
+confirmed by testing that a **Cloud** or even a **WSL** session shows the
+install as complete and "Connected" but exposes no tools at all, silently.
+Check the session-type picker (Local/Cloud/Remote Control/WSL/SSH,
+wherever new chats/tasks get created) before assuming a broken install.
+Codex was confirmed working in a normal chat with no equivalent
+restriction. See the "Local session required" sections in
+[`claude-code-plugin/README.md`](claude-code-plugin/README.md) and
+[`claude-desktop-extension/README.md`](claude-desktop-extension/README.md)
 for the exact symptoms and how to check for it.
 
 ## Versioning

integrations/claude-code-plugin/README.md

@@ -6,6 +6,12 @@ CircuitPython board directly — filesystem transfer, REPL/exec, a
 non-interrupting `watch_repl`/`probe` pair for long-running scripts, and
 firmware build/flash.
 
+**Also used by Codex.** Codex's own Plugins panel reads this same
+marketplace/plugin format directly — confirmed working via
+**Plugins → Add → Add plugin marketplace**, Source `PyDevices/mpftp`. See
+[`../codex/README.md`](../codex/README.md). The "Local session" caveat
+below is Claude-specific; Codex didn't show it.
+
 ## Install
 
 Requires `pydevices-mpftp` on `PATH` (`pip install pydevices-mpftp`) —

integrations/codex/README.md

@@ -1,23 +1,47 @@
-# mpftp for Codex CLI
+# mpftp for Codex
 
-[Codex](https://developers.openai.com/codex) doesn't have an installable plugin
-system — MCP servers are registered directly in its config file. Add the mpftp
-server to `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):
+Codex has two integration points, and both were confirmed working
+end-to-end (connect, filesystem, and REPL against a real board) —
+**no equivalent of the Claude Desktop app's "Local session required"
+restriction**; it just worked in a normal Codex chat.
+
+## Option A — Plugins panel (Codex app, GUI)
+
+Codex's Plugins panel reads the **same** plugin files this repo already
+ships for Claude Code — no separate Codex-specific package:
+
+1. Codex app → **Plugins** (left sidebar) → **Add** → **Add plugin marketplace**.
+2. **Source**: `PyDevices/mpftp`. Leave **Git ref** as `main` and
+   **Sparse paths** empty — the repo root's `.claude-plugin/marketplace.json`
+   already points at [`../claude-code-plugin/`](../claude-code-plugin/), the
+   same directory Claude Code installs from.
+3. Install the `mpftp` plugin from the marketplace that appears. It shows
+   up with **MCP servers: 1** (`mpftp`) and **Skills: 1** (`Board Tools`).
+
+Requires `pydevices-mpftp` installed (`pip install pydevices-mpftp`) so
+`mpftp-mcp` resolves on `PATH` wherever Codex spawns the server.
+
+## Option B — bare `codex` CLI, no GUI
+
+For headless `codex` CLI use (no Plugins panel available), register the
+MCP server directly in its config file instead:
 
 ```toml
 [mcp_servers.mpftp]
 command = "mpftp-mcp"
 ```
 
-Or via the CLI:
+in `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`), or:
 
 ```bash
 codex mcp add mpftp -- mpftp-mcp
 ```
 
-`mpftp-mcp` is the console script `pip install pydevices-mpftp` puts on
-`PATH` (`python -m mpftp.mcp` also works if you'd rather pin an explicit
-interpreter). It needs to be the same interpreter mpftp's own CLI uses — on
+This path has no bundled skill — see
+[`docs/agent-guide.md`](../../docs/agent-guide.md) via `AGENTS.md` instead
+(also covered below).
+
+`mpftp-mcp` needs to be the same interpreter mpftp's own CLI uses — on
 WSL, the one that can see your board's `COM` port (usually Windows
 `python.exe`), the same choice `mpftp.pythonPath` makes for the VS Code
 extension.