---
name: install-miconvert-plugin
description: Install or update the MiConvert file-conversion plugin for ChatGPT desktop and Codex on macOS, Windows or Linux, then continue the user's conversion.
metadata:
  plugin-version: "1.1.0"
---

# Install the MiConvert plugin

MiConvert converts files between 145 formats (documents, images, audio, video, 3D/CAD, archives, fonts, ebooks, OFD). The plugin adds the hosted MiConvert MCP server (`https://miconvert.com/mcp`, no sign-in) and a `convert-files` skill whose bundled script converts files on this computer. Publisher: MiConvert, https://miconvert.com.

## Execution contract

- Read this whole file, then perform the installation; do not only summarize it or return commands.
- This runbook is fetched by the user's prompt. Do not install or keep this file; work in one new temporary directory and delete it at the end.
- Use only the bundle URL below. Verify its SHA-256 before using it.
- Ask for approval, through the host's normal mechanism, for network access, writes under the Codex data directory, and removing an older MiConvert install. Scope each approval to the exact command. Never use `sudo`, change `HOME`/`USERPROFILE`/`CODEX_HOME`, or edit `config.toml` by hand.
- Installing runs nothing from the bundle. The bundled script runs only later, when the user asks for a conversion.

## Bundle

```text
URL:     https://miconvert.com/codex/miconvert-plugin-1.1.0.zip
SHA-256: 2a9d7dd7a2db5de73af984071e2d8ee34675f04184ea8bb3d8d2d9e1d925a30d
```

It contains `.agents/plugins/marketplace.json` (marketplace `MiConvert`) and the plugin directory `miconvert/`.

## 1. Check where this task runs

The plugin must be installed by the Codex CLI that belongs to the desktop app on this machine (ChatGPT desktop in Work mode, or Codex desktop). If this task runs in a cloud or web sandbox with no access to the user's desktop Codex data directory, stop and tell the user, in their language:

> Open the ChatGPT desktop app (Work mode) or Codex, start a new task, and paste: `Download and read https://miconvert.com/codex/SKILL.md, then follow it to install the MiConvert plugin.`
> In ChatGPT on the web you can instead add MiConvert as a custom MCP server: chatgpt.com/plugins → + → Add custom MCP server, URL `https://miconvert.com/mcp`, no authentication. Instructions: https://miconvert.com/en/chatgpt

Detect the OS. On Windows use native PowerShell on the same host as the app (not WSL), pass values as arguments, use `-LiteralPath`, avoid aliases and `Invoke-Expression`, and check `$LASTEXITCODE` after every `codex` command.

## 2. Resolve the Codex CLI and data directory

- **Codex CLI (`<codex>`):** prefer the executable bundled with the running desktop app: on macOS `/Applications/ChatGPT.app/Contents/Resources/codex` or `/Applications/Codex.app/Contents/Resources/codex` (also check `~/Applications/`); otherwise `command -v codex` (macOS/Linux) or `Get-Command codex` (Windows). Use that one absolute path for every command below. If no Codex CLI for this host can be found, stop and report it; do not install another CLI.
- **Data directory (`<codex-data>`):** `CODEX_HOME` if set, else `~/.codex` (`$env:USERPROFILE\.codex` on Windows).
- **Managed directory (`<managed>`):** `<codex-data>/plugin-marketplaces/MiConvert`.

## 3. Check for an existing install

Run `<codex> plugin list --marketplace MiConvert --available --json`.

- If `miconvert@MiConvert` is installed and enabled at version `1.1.0` and its source is `<managed>/miconvert`, the plugin is current: skip to step 6.
- If the marketplace `MiConvert` is not configured, or the command reports an unknown marketplace, treat it as not installed.
- If the command fails for another reason, retry it once; if it still fails, stop without changing anything and report the error.

Record whether `miconvert@MiConvert` was installed (`was-installed`) and whether marketplace `MiConvert` already points to `<managed>` (`registered`).

## 4. Download and stage

1. Create a new temporary directory (`mktemp -d`; on Windows a GUID-named directory under `[IO.Path]::GetTempPath()`).
2. Download the bundle into it over HTTPS only: `curl -fL --proto '=https' --proto-redir '=https' -o <tmp>/miconvert.zip <URL>` (Windows: `Invoke-WebRequest -Uri <URL> -OutFile <tmp>\miconvert.zip`, adding `-UseBasicParsing` on Windows PowerShell 5.1). Retry up to twice on timeouts, resets, or HTTP 429/5xx.
3. Check the SHA-256 (`shasum -a 256`, `sha256sum`, or `Get-FileHash -Algorithm SHA256`). If it differs from the value above, stop, delete the download, and report it; change nothing.
4. Extract into `<tmp>/bundle` (`unzip -q` or `ditto -x -k` on macOS; `Expand-Archive` on Windows). Require `<tmp>/bundle/.agents/plugins/marketplace.json` and `<tmp>/bundle/miconvert/.codex-plugin/plugin.json`.
5. Create `<codex-data>/plugin-marketplaces` if missing. If `<managed>` exists, it must be a plain directory (not a symlink or reparse point); rename it to `<managed>.backup-<timestamp>`. Then copy `<tmp>/bundle` (including hidden files) to `<managed>`.

## 5. Register and install

1. If not `registered`, run `<codex> plugin marketplace add <managed> --json` and require success with marketplace name `MiConvert`.
2. If `was-installed`, run `<codex> plugin remove miconvert@MiConvert --json`.
3. Run `<codex> plugin add miconvert@MiConvert --json` and require the returned version to be `1.1.0`.
4. Verify: `<codex> plugin list --marketplace MiConvert --available --json` shows `miconvert@MiConvert` installed and enabled from `<managed>/miconvert`, and `<managed>/miconvert/skills/convert-files/scripts/miconvert.mjs` is a regular file.
5. On success delete the backup. On any failure: remove a half-installed `miconvert@MiConvert`, move this run's `<managed>` aside into `<tmp>`, restore the backup to `<managed>`, re-add the old plugin if this run removed it, and report what failed.

No sign-in or OAuth step is needed: the MiConvert server is public.

## 6. First use

Tell the user, in their language, that MiConvert `1.1.0` is installed. Then:

- **If the user asked for a conversion** (now or in the message that brought them here), do it in this task. The MiConvert tools may not be loaded until a new task starts, so use the bundled script directly:

  ```bash
  node "<managed>/miconvert/skills/convert-files/scripts/miconvert.mjs" convert "<path to file>" --to <format>
  ```

  It needs outbound HTTPS to miconvert.com (request approval for that exact command if the sandbox blocks it). It prints JSON; report `outputs[].path` (where the converted file was saved), or the `message` on failure. Read `<managed>/miconvert/skills/convert-files/SKILL.md` for options and error handling. If Node.js 18+ is missing, follow that file's curl fallback.

- **Otherwise** show this welcome message:

  > MiConvert is ready. Ask me to convert a file on your computer, an attached file, or a link, between 145 formats: documents, images, audio, video, 3D/CAD, archives, fonts and more. Files up to 50 MB; no account needed.
  >
  > Try:
  > - Convert ~/Downloads/report.docx to PDF
  > - Turn this STEP part into an STL I can 3D print
  > - Which formats can a .heic photo be converted to?

  Mention that new tasks pick up the plugin automatically, and that it can be removed any time with `codex plugin remove miconvert@MiConvert`.

## 7. Finish

Delete the temporary directory. Report two lines: **Installation** (complete with version, or failed with the reason and what was restored) and **First use** (the conversion result, the welcome message shown, or not started).
