Plugin Installation

How claudeBase verifies and installs plugins securely.

Allowlist Model

Only plugins published to the official claudeBase catalog can be installed. This ensures every plugin has been reviewed and verified.

No arbitrary packages. You cannot install directly from npm or GitHub. All plugins must be in the catalog.

Installation Flow

Step 1: Catalog Lookup

CLI looks up the plugin name in the cached catalog. If not found and not offline, attempts one refresh.

Step 2: Visibility Check

Checks if plugin is revoked or unlisted. Revoked plugins are blocked. Unlisted require --allow-unlisted.

Step 3: Download

Downloads the tarball from npm registry (@claudebase/ scope only).

Step 4: Verification

Verifies tarball safety: no symlinks, no path traversal, no lifecycle scripts, integrity hash match.

Step 5: Extraction

Extracts to ~/.claude/plugins/<name>/ with atomic rename for safety.

Safety Validations

Every plugin tarball is verified for:

✓No symlinks - All entries must be regular files
✓No path traversal - No .. or absolute paths
✓Allowed locations only - .claude-plugin/, skills/, or specific root files
✓No lifecycle scripts - No postinstall, prepare, etc.
✓No executables - No bin field in package.json
✓Integrity match - All files verified against integrity.json
✓Windows safety - Reserved names and ADS blocked

Version Handling

Scenario	Behavior
Upgrade (newer version)	Automatically allowed
Same version	Skipped (use --force to reinstall)
Downgrade (older version)	Blocked (use --allow-downgrade)

Revoked Plugins

If a plugin is revoked, new installations are blocked but existing installations remain untouched. You must manually remove revoked plugins with claudebase plugin remove.