Publish an add-on

You can share a .cmxaddon file directly. Users import it from Settings → Add-ons → Import package, and CodeMux labels it Local / unverified. To be listed on codemux.org/addons and install from Browse or an install link, a release has to go through catalog review.

The catalog is new, and it stays empty until the first reviewed releases are published.

1. Prepare the release

• Use your real publisher in the manifest id. It can't change after anyone installs the add-on.
• Set author, repository and license correctly, and put the matching license text in LICENSE. The repository has to be public.
• Use a stable version such as 1.2.0. Catalog releases can't be pre-releases.
• Commit your source, then run npm run check and npm run pack from that exact commit. Packing is reproducible, so the same source gives the same bytes.

2. Create a GitHub Release

Attach the .cmxaddon to a GitHub Release in the repository from your manifest, with a tag that points to the commit you built. For example:

npm run pack
gh release create v1.2.0 acme.issue-helper-1.2.0.cmxaddon \
  --target "$(git rev-parse HEAD)" --title "Issue Helper 1.2.0"

Record the SHA-256 that pack prints and the file's size in bytes. Never replace the file for a version you've released. A version always refers to the same bytes. To fix something, release a new version.

3. Submit a catalog entry

Catalog entries live in the public CodeMux repository. Open a pull request that adds catalog/addons/entries/<publisher.name>.json. For an update, add the new release to your existing entry and keep the old ones. The file follows the Plugin definition in catalog/addons/schema/catalog-v1.json:

{
  "id": "acme.issue-helper",
  "name": "Issue Helper",
  "publisher": "acme",
  "tier": "community",
  "description": "Browse issues and add one to a chat draft.",
  "readme": "Browse your repository's open issues and add one to the chat draft.",
  "repository": "https://github.com/acme/issue-helper",
  "releases": [
    {
      "version": "1.2.0",
      "api": "^1.0.0",
      "platforms": ["linux-x64", "windows-x64"],
      "sourceCommit": "<full 40-character commit SHA>",
      "downloadUrl": "https://github.com/acme/issue-helper/releases/download/v1.2.0/acme.issue-helper-1.2.0.cmxaddon",
      "sha256": "<sha256 printed by pack>",
      "compressedBytes": 48213,
      "publishedAt": "2026-10-01T12:00:00Z",
      "license": "MIT",
      "capabilities": {
        "permissions": ["composer.append", "external.open"],
        "http": [{ "origin": "https://api.github.com", "methods": ["GET"], "credential": "github-token" }],
        "credentials": [{ "id": "github-token", "label": "GitHub token (optional)", "origin": "https://api.github.com", "type": "bearer" }]
      }
    }
  ]
}

capabilities repeats the manifest's permissions, network access and credentials. Sort permissions, origins, methods and credential IDs. Maintainers decide the tier (official or community).

4. Review

Automated checks confirm that the tag points to sourceCommit, download the asset, compare its hash and size, and validate the archive the same way the desktop app does. They never run your code.

Maintainers then review:

• The source at that commit, and the diff since your last release.
• Dependency changes.
• Any new permissions, origins, methods or credentials.
• Whether you control the repository and publisher name.
• How the release was built, and its license.

After the entry is merged, maintainers publish a new catalog revision and update the website to it. The desktop app picks it up the next time it refreshes the catalog.

Updates and removal

Users update manually with Check for update. If a new version asks for more access, they review it again before it's enabled. Otherwise it keeps their existing grants. They can roll back to the previous version.

Maintainers can block a plugin ID or a single file digest. A blocked add-on is turned off the next time CodeMux refreshes the catalog. Report a listing or a security issue through the CodeMux repository.

A catalog listing means the release was reviewed. It doesn't guarantee that the add-on is free of bugs.