Custom plugins

Custom plugins are Claude Code plugins that your team writes itself, instead of installing them from a public marketplace. Claude Sync brings the plugin files to every machine, and on every machine the plugin is installed and enabled.

Not to be confused with the Plugins domain

The Plugins domain syncs the list of plugins installed from a marketplace: you install once and the plugin shows up everywhere, you remove it and it disappears everywhere, but the package always comes from the marketplace. With custom plugins the plugin itself travels, because you wrote it and it doesn’t exist on any marketplace. See What it syncs.

Where they live

Custom plugins live in the custom-plugins folder, inside the Claude Code folder (~/.claude). The folder also contains:

• the custom-plugins.json file, the list of the team’s plugins;
• a README that explains how to prepare a plugin;
• a .knmsyncignore file, which says which files must not travel (see What stays on the machine below).

How to create and distribute a plugin (maintainer)

1. Create the plugin’s folder inside custom-plugins.
2. Add the plugin to custom-plugins.json with its name, its state (enabled or not), the setup script if there is one, and an optional note.
3. Also register it in the .claude-plugin/marketplace.json file in the same folder, as the README explains.
4. Click Sync now. The plugin goes to the team repository and from there reaches the other machines.

From the dashboard, the maintainer opens the plugin list and the README with one click.

What happens on every machine

On every machine everything happens on its own, with no button to press. At each sync, every new or changed plugin, if it’s enabled, is installed and enabled in Claude Code.

• If the plugin has a setup script, it runs to install what the plugin needs. The script can have a version for each operating system.
• If setup fails, the plugin stays installed and the dashboard marks it Setup failed. Syncing carries on as usual.
• A plugin disabled or removed from the list is uninstalled on every machine.

In the dashboard

Plugins tab

Custom plugins also appear in the Plugins tab, read-only, each with its status (Installed, Pending or Setup failed) and the note Manage these in Claude system › Custom plugins.

Custom plugins in the Plugins tab; you manage them from Claude system › Custom plugins.

Claude system tab › Custom plugins

In the Claude system tab, the Custom plugins section gathers the team’s plugins, with the number of plugins and the Open folder button. For each plugin you see its name, notes, status and Open.

• The maintainer has the switch to enable or disable it and the Delete button, with two-click confirmation: both apply to the whole team at the next sync.
• Like skills, a custom plugin can be shared with the team or kept to yourself (Only yours label).
• Members see the status, the Open button and whether the plugin is enabled, without being able to change it.

A plugin deleted for the whole team disappears from every machine. At the bottom of the section the maintainer finds the Deleted by the team list, with Revive next to each name: Revive allows the name again, so the plugin can be shared again. You can recover the earlier files from the repository history or from a backup.

The Custom plugins section as the maintainer sees it (Team edition example).

Turning custom plugins on or off on a machine

In the System tab, the Custom plugins card has the Custom plugins sync switch. The state the maintainer chooses is the team default, and new machines inherit it; every machine, of any role, can still turn it off for itself.

The automatic plugin installation setting only concerns marketplace plugins, not custom plugins.

What stays on the machine

A plugin travels as source, without the files a build produces. That’s why the folder already contains a .knmsyncignore, with the same syntax as a .gitignore (see What it syncs). It excludes the most common files that make no sense on another machine: node_modules/, bin/, obj/, dist/, .git/ and compiled libraries such as *.exe, *.dll, *.so, *.dylib. You can edit it: add what your plugin generates, or remove a rule you don’t need. The maintainer opens it straight from the dashboard.

Programs a plugin needs are best installed by its setup script, rather than put in the package.

Pro and Team editions

Custom plugin syncing is included in the Pro and Team editions. Without a license that includes it, its controls don’t appear in the dashboard.

See also

• What it syncs: all the domains, including the Plugins domain.
• Editions: which editions include custom plugins.
• Managing the configuration: sharing, keeping to yourself, turning off.
• The dashboard: the Plugins and Claude system tabs.