Custom plugins

Custom plugins are the Claude Code plugins your team writes itself, instead of installing them from a public marketplace. Claude Sync carries them to every machine: not just the fact that they are installed, but the plugin’s own files travel through the team repository.

Don’t confuse this with the Plugin domain

The Plugin domain syncs the inventory of plugins installed from a public or git marketplace: install once and the plugin appears everywhere, remove it and it disappears everywhere — but the package always comes from the marketplace. Custom plugins are a different thing: here it is the plugin itself that travels, because you wrote it and it exists on no marketplace. For the full picture of the domains see What it syncs.

Where they live

Custom plugins live in a custom-plugins folder inside the Claude Code configuration folder (~/.claude). That folder acts as a small local marketplace for Claude Code, and it also holds:

• the team manifest custom-plugins.json, which lists the shared plugins;
• a README explaining the format of a bundle;
• a .knmsyncignore file that declares which files are not carried across machines (see Limits and availability below).

The lifecycle

Authoring (maintainer)

Authoring a custom plugin is a file-based operation, reserved for the maintainer:

• drop the bundle folder into custom-plugins;
• declare it in custom-plugins.json with a name, its state (enabled or disabled), an optional setup script, and optional notes.

The README in the folder describes the format to follow. From the dashboard, the maintainer has quick-open buttons for the manifest and the README. There is no in-app wizard: authoring is file-based by design.

Publishing

At the next sync the bundle is shipped to the team repository. From there it reaches every other machine.

Receiving (every machine, automatic)

On every machine, receiving is fully automatic — no button to press. On each sync, every new or changed plugin that is enabled is registered with Claude Code, installed, and enabled.

• If the plugin declares a setup script, it runs to prepare prerequisites (per-OS variants are supported, so each machine runs the right one for Windows, macOS, or Linux).
• If setup fails, the plugin stays installed but is flagged Setup failed in the dashboard: the sync is never blocked by it.
• A plugin that is disabled or removed from the manifest is uninstalled automatically on every machine.

In the dashboard

Plugins tab

Custom plugins also appear in the Plugins tab as a read-only mirror, each with a state pill — Installed, Pending, or Setup failed — and a note, Manage these in Claude system › Custom plugins, pointing you to where they’re managed.

Custom plugins appear in the Plugins tab as a read-only mirror; they are managed from Claude system › Custom plugins.

Claude System tab → Custom plugins

In the Claude System tab, a Custom plugins accordion gathers the team’s plugins: a count, the description “Team plugins installed on every machine.”, and a button to open the folder. For each plugin you find the name, notes, a state pill, and an Open button. The maintainer also gets, per plugin, an enable/disable toggle and a delete button (armed, with double-click confirm): both act for the whole team at the next sync. Members see only the read-only state pills.

A team-wide deletion sticks: a machine that was behind won’t reinstall the plugin later. At the bottom of the accordion the maintainer finds a Deleted by the team list with a Revive button next to each removed name — Revive re-allows the name so the plugin can be shared again; it does not bring back the old files (recover those from git history or a backup).

The Custom plugins accordion in the Claude system tab (Team edition example), with the per-plugin state and the maintainer controls.

The domain card

A dedicated Custom plugins card, alongside the hook toggles, offers the domain’s on/off toggle (setting: “Sync the team’s custom Claude Code plugins across machines.”).

Governance

The maintainer’s toggle is the team default: new machines inherit it. But every machine — of any role — can flip its own copy locally to opt out of the domain. In short: the maintainer’s toggle is the team default; each machine can opt out locally.

The separate auto-install plugins setting concerns only the marketplace-plugins inventory, not custom plugins.

Limits and availability

A bundle is meant to carry the plugin’s source, not the build output a compiled plugin naturally piles up. To keep that output at home, the folder ships with a ready-made .knmsyncignore file — the same .gitignore-style declaration described in What it syncs. By default it excludes the usual non-portable artifacts (node_modules/, bin/, obj/, dist/, .git/, and compiled libraries such as *.exe, *.dll, *.so, *.dylib). This is a plain, editable declaration, not a fixed rule: extend it to cover whatever your own bundle generates, or trim it if you need to. You can open and edit the file directly from the dashboard.

Real binaries a plugin depends on are best treated as prerequisites installed by its setup script, rather than shipped inside the bundle.

Pro and Team editions

Custom-plugin sync is included in the Pro and Team editions, not in Starter. Without a license that includes it — or if you turn the domain off — its tabs and controls do not appear at all in the dashboard: they are not greyed out, they simply are not there.

See also

• What it syncs — the domains and what travels in each, including the Plugin domain this is distinct from.
• Editions — which editions unlock custom plugins.
• Managing your configuration — turning sync domains on and off.
• The dashboard — the Plugins and Claude System tabs, one by one.