Manifest reference

manifest.json tells CodeMux what your add-on is, which surfaces it adds and what it's allowed to do. CodeMux validates the manifest and shows it to the user for review before it runs any of your code. codemux-plugin check uses the same rules as the desktop app, so a manifest that passes check also passes import. The SDK includes the JSON Schema as @codemux/plugin-sdk/schema.

Example

{
  "format": "codemux.feature-plugin",
  "manifestVersion": 1,
  "id": "acme.issue-helper",
  "name": "Issue Helper",
  "description": "Browse issues and add one to a chat draft.",
  "version": "1.0.0",
  "api": "^1.0.0",
  "entry": "plugin.js",
  "platforms": ["linux-x64", "windows-x64"],
  "author": { "name": "Acme", "url": "https://acme.example" },
  "repository": "https://github.com/acme/issue-helper",
  "license": "MIT",
  "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" }
  ],
  "contributes": {
    "commands": [{ "id": "open", "title": "Open Issue Helper", "requiresWorkspace": true }],
    "panels": [{ "id": "issues", "title": "Issue Helper", "icon": "github" }],
    "composerActions": [{ "id": "browse", "title": "Browse issues", "icon": "github" }],
    "composerViews": [{ "id": "issues", "title": "Issue Helper", "icon": "github" }]
  },
  "settings": [
    { "id": "owner", "type": "string", "label": "Repository owner", "default": "" }
  ]
}

Every field is required. Arrays can be empty, but they have to be present. Unknown fields, duplicate IDs and duplicate JSON keys are rejected. The whole file can be up to 64 KiB.

Fields

Text fields can't contain control characters. URLs must be HTTPS and can't include a username or password.

Permissions

A host call that needs a permission you didn't declare rejects with PERMISSION_DENIED. The review shows each permission to the user in plain words.

Opening your own panels and composer views, settings, storage and notifications don't need a permission.

Network access and credentials

Add-ons can't use fetch. ctx.http.fetch can only reach the origins you declare in http, using the methods you list:

"http": [
  { "origin": "https://api.example.com", "methods": ["GET", "POST"], "credential": null }
]

• origin is an exact lowercase https://host, with no path, port, wildcard, IP address or trailing dot. Only port 443 is used. Each origin can appear once, and you can declare up to 20.
• methods are any of GET, POST, PUT, PATCH and DELETE. The review warns the user when an add-on can write to an external service.
• credential is null or the ID of a credential for the same origin.
• CodeMux refuses private, loopback and link-local addresses, so an add-on can't reach localhost or your local network.

A credential is a bearer token that the user enters in the add-on's page under Settings → Add-ons:

"credentials": [
  { "id": "api-token", "label": "API token", "origin": "https://api.example.com", "type": "bearer" }
]

type is always "bearer". Each origin can have one credential, and the http entry for that origin has to reference it. CodeMux keeps the token in the system's credential store and adds it to matching requests. Your code never sees it. Don't ask for tokens in regular settings.

Contributions

Each contribution needs a callback registered in activate. See the SDK API reference.

IDs are 1–40 characters of a-z, 0-9 and -, and start with a letter. Titles are 1–80 characters. Set requiresWorkspace to true for commands that only make sense with a project open.

Composer actions and views only appear when the chat UI is on. Panels and commands work either way. In a remote workspace or a browser client, add-on commands and panels don't appear at all.

Icons

Contributions and the Icon component use the same set: file-text, git-branch, github, list, check, info, settings, book-open, link, refresh-cw, plus, circle-alert, folder, terminal, code and search. The SDK also exports them as ICONS and the IconName type.

Settings

Settings appear on the add-on's page under Settings → Add-ons, and CodeMux renders the fields. Read them with ctx.settings.get() and watch for changes with ctx.settings.subscribe(). You can declare up to 50.

Every setting has id, type, label and default (optional for string). Setting IDs follow the same rules as contribution IDs, so use include-files, not includeFiles.

Package contents

codemux-plugin pack writes a gzip-compressed tar with the extension .cmxaddon. It can contain only these files, at the root:

A package can be up to 10 MiB compressed and 30 MiB uncompressed. It can't contain scripts, native binaries, nested dependencies, links or folders.