Skip to content
Cortex

Manifest and Capabilities

Define plugin identity, bundle paths, and runtime permissions for reviewed extension behavior.

2 min readEdit on GitHub

Every community plugin has a manifest.json at the plugin root. The plugin entry imports it and passes it to definePlugin, so the loader and the bundle always agree on the id.

Manifest Shape#

json
{	"id": "example-plugin",	"name": "Example Plugin",	"version": "0.1.0",	"minAppVersion": "0.1.0",	"author": "Your Name",	"authorUrl": "https://example.com",	"description": "Adds a sample command and sidebar view.",	"icon": "puzzle",	"main": "dist/index.js",	"permissions": ["vault:read", "workspace:tabs"]}
ts
import { definePlugin, type PluginManifest } from "@cortex.md/api"import manifest from "../manifest.json"export default definePlugin({	manifest: manifest as PluginManifest,})
FieldRequiredNotes
idYesStable id unique inside a vault. Must match the bundle and the Marketplace entry.
nameYesUser-facing name; also labels the plugin settings page.
versionYesPlain MAJOR.MINOR.PATCH. Pre-release suffixes break update checks.
minAppVersionYesMinimum Cortex version the plugin expects.
authorYesDisplayed in plugin and Marketplace surfaces.
authorUrlNoPublic URL for the author or organization.
descriptionYesShort install/review summary.
iconYesLucide icon name.
mainYesSafe relative path to the bundle, usually dist/index.js.
permissionsNoRuntime context APIs the plugin calls. Unknown values fail the load.

When you release, the CLI mirrors permissions into a capabilities field of the release manifest.json automatically. Do not maintain it by hand.

Contributions Need No Permission#

Commands, views, sidebar items, status bar items, context menu items, settings, Markdown rules, property types, fold providers, and editor extensions are granted by declaring them under contributes. The plugin's capabilities are derived from that declaration.

Runtime Permissions#

PLUGIN_PERMISSIONS lists every value. A context call without its permission throws (or, for notifications, returns { delivered: false, reason: "missing-capability" }).

PermissionEnables
vault:readctx.vault reads, listings, exists, getVaultPath, and ctx.metadata.
vault:writectx.vault.writeFile.
vault:deletectx.vault.deleteFile.
vault:watchctx.vault.onFileEvent.
editor:readActive file path and content.
editor:writeinsertAtCursor and replaceSelection.
workspace:tabsOpening files, plugin views, and temporary Markdown tabs; open-file reads.
theme:readActive theme name and theme change subscriptions.
bookmarks:readBookmark list, lookup, and change subscriptions.
bookmarks:writeAdd, remove, and toggle bookmarks.
dataPlugin-owned data files.
notificationsNative notifications and ctx.ui.showNotice.

Best Practices#

  • Request the narrowest set of permissions you need; permissions are user-visible.
  • Do not call APIs defensively and ignore permission failures. Declare the permission or remove the feature.
  • Use local ids for plugin commands, views, settings, and context menu items. Cortex prefixes where global uniqueness is needed.

Search docs

Search Cortex documentation pages and headings.