Build an add-on

An add-on is a small TypeScript and Preact project that you bundle into a single .cmxaddon package. CodeMux runs it in an isolated QuickJS process and renders its UI with CodeMux's own components. You don't need a CodeMux checkout, and you don't need to rebuild the app.

This page takes you from an empty folder to a running add-on. When you're done, read the Project Brief walkthrough for a complete example. The reference pages cover the manifest, the SDK API and UI components.

The add-on platform is in preview. The SDK and CLI are version 1.0.0 (plugin API ^1.0.0) and aren't on npm yet, so you install them from packed tarballs, as shown below. When they're published, only the install step changes.

Requirements

• Node.js 20 or later. Node is only needed on your machine. CodeMux never runs npm, installs dependencies, or runs package scripts.
• A CodeMux build with Settings → Add-ons.
• Git, to get the SDK source while the packages aren't on npm yet.

Add-ons run on linux-x64 and windows-x64.

1. Get the SDK and CLI

Build and pack both packages from the public CodeMux repository:

git clone https://github.com/Zeus-Deus/codemux.git
cd codemux/packages/plugin-sdk
npm ci --ignore-scripts
npm run build
npm pack --ignore-scripts --pack-destination ~/codemux-sdk
cd ../plugin-cli
npm pack --ignore-scripts --pack-destination ~/codemux-sdk

~/codemux-sdk now contains codemux-plugin-sdk-1.0.0.tgz and codemux-plugin-cli-1.0.0.tgz. Your add-on project uses these two files. It never imports anything from the CodeMux source.

2. Create a project

Run the CLI's init command from the directory where the project should go:

npx --yes --package ~/codemux-sdk/codemux-plugin-cli-1.0.0.tgz \
  codemux-plugin init my-addon --id acme.my-addon
cd my-addon
npm install ~/codemux-sdk/codemux-plugin-sdk-1.0.0.tgz \
  ~/codemux-sdk/codemux-plugin-cli-1.0.0.tgz

--id is your add-on's permanent ID, written as publisher.name. Without it, the ID is example.<directory name>. Set the real publisher before anyone installs the add-on, because the ID can't change afterwards.

Installing the tarballs replaces the SDK and CLI versions in package.json with file: paths. After the packages are published, change them back to 1.0.0 and run npm install.

The starter contains:

The starter declares one workspace.read permission, a panel called main, a command that opens it, and a second command that shows a notification. Before you publish, replace the Example author, repository URL and LICENSE holder with your own.

3. Build, check and pack

npm run build   # bundles src/index.tsx and the SDK into plugin.js
npm run check   # type-checks, then validates manifest.json and required files
npm run pack    # writes acme.my-addon-1.0.0.cmxaddon and prints its SHA-256

The build creates a single bundle with no runtime imports. process, require, fetch and the browser DOM aren't available, so libraries that need a real DOM won't work. Dynamic import() fails the build.

4. Install it in CodeMux

1. Open Settings → Add-ons and choose Import package.
2. Select your .cmxaddon file. CodeMux shows a review with the parsed name, version, digest, and every permission, network origin and credential the package declares. An imported file is labeled Local / unverified.
3. Choose Install & enable. If you only choose Install, the add-on stays installed but inactive until you enable it.

After it's enabled, your contributions show up here:

CodeMux starts an add-on the first time one of these needs it. It stops the add-on after 60 seconds with no open view.

5. Iterate with Developer mode

Importing a new package after every change gets slow. Developer mode reloads your package automatically when it changes:

1. Run npm run dev in your project. It rebuilds on every change to src/, manifest.json, README.md, LICENSE or NOTICE, and always writes dist/<id>.cmxaddon. A failed build is printed and the watcher keeps running.
2. In Settings → Add-ons, turn on Developer mode.
3. Choose Select development package, pick dist/<id>.cmxaddon, and choose Install & enable in the review. CodeMux only watches the file if you pick Install & enable. It doesn't watch if you pick Install or enable the add-on later.

CodeMux now reloads each validated rebuild with the access you already accepted. It keeps watching until you disable the add-on or turn off Developer mode. To reload by hand, use Reload <id>. Some things still need your input:

• If a rebuild adds or changes permissions, network access or credentials, you get a new review.
• A runtime error stops the add-on. Reloads don't restart it. Choose Retry in Settings → Add-ons.
• Developer mode turns off every time CodeMux starts.

CodeMux only watches the one package you select. It doesn't look for source folders, and no website link can load a file from your machine.

Next steps

• Follow the Project Brief walkthrough to build a panel that reads Git status and adds text to the chat draft.
• Look up permissions and contributions in the Manifest reference.
• Look up host calls, error codes and limits in the SDK API reference.
• Build your UI with the components.
• When it's ready, publish a release.