Manifest

The manifest is the package.json at the root of the extension. name and version sit at the top level; everything Muxy-specific sits under muxy.

{
  "$schema": "https://raw.githubusercontent.com/muxy-app/muxy/main/docs/extensions/schema/manifest.schema.json",
  "name": "hello",
  "version": "0.1.0",
  "scripts": { "build": "vite build && cp package.json dist/" },
  "muxy": {
    "description": "Says hello",
    "permissions": ["notifications:write"],
    "commands": [{ "id": "ping", "title": "Hello: Ping" }]
  }
}

The JSON schema gives editor completion when $schema sits at the top level. In VS Code it replaces the built-in package.json schema for that file. The schema checks publishable packages, so it also requires scripts.build. Muxy ignores $schema and other keys it doesn't know.

Loading

Muxy reads dist/package.json when it exists, otherwise package.json.
Every path in the manifest (entry, background, script, icons) is relative to dist/ when the folder has one, otherwise to the folder itself. Paths can't leave that folder.
An invalid manifest shows as a load error in Settings → Extensions.

Top-level fields

Field	Required	Notes
`name`	yes	The extension ID. Use `a-z`, `0-9`, `.`, and `-`; pages don't load for other names. Must match its folder name when published or installed.
`version`	yes	Semver. Bump it for every published change.
`scripts.build`	to publish	Must leave `package.json` in `dist/`.

`muxy` fields

The muxy object is required; its fields are optional.

Field	Type	See
`description`	string	One line, shown in Settings.
`permissions`	string[]	Permissions
`events`	string[]	Workspace events it may receive. Events
`background`	string	Path to a script that runs while the extension is enabled. Events
`commands`	object[]	Commands
`tabTypes`	object[]	Tabs
`fileOpeners`	object[]	Tabs
`panels`	object[]	Panels
`popovers`	object[]	Panels
`sidebar`	object	Panels
`topbarItems`	object[]	Bar items
`statusBarItems`	object[]	Bar items
`localizations`	object[]	Localizations
`settings`	object[]	Settings below
`marketplace`	object	Listing details. Contributing

homeViews and remoteMethods are accepted for 1.x compatibility but do nothing yet.

IDs must be unique within their list, and every reference (a command's panel, an item's command) must exist.

Icons

Panels, the sidebar, and bar items take an icon:

{ "icon": "sparkles" }
{ "icon": { "symbol": "sparkles" } }
{ "icon": { "svg": "assets/icon.svg" } }

symbol is an SF Symbol name. Linux has no SF Symbols: it draws the common ones from its own icons and the extension icon in place of the rest.
svg is a file of up to 256 KiB. It is tinted like the app's own icons, so use currentColor or one solid color. It looks the same on macOS and Linux.

Settings

Declared settings appear on the extension's page in Settings → Extensions.

"settings": [
  { "key": "greeting", "title": "Greeting", "type": "string", "defaultValue": "Hello" },
  { "key": "loud", "title": "Shout", "type": "bool" }
]