`genesis plugins`

Manage Gateway plugins, hook packs, and compatible bundles.

Plugin system: Plugins
Bundle compatibility: Plugin bundles
Plugin manifest + schema: Plugin manifest
Security hardening: Security

Commands

genesis plugins list
genesis plugins list --enabled
genesis plugins list --verbose
genesis plugins list --json
genesis plugins install <path-or-spec>
genesis plugins inspect <id>
genesis plugins inspect <id> --json
genesis plugins inspect --all
genesis plugins info <id>
genesis plugins enable <id>
genesis plugins disable <id>
genesis plugins uninstall <id>
genesis plugins doctor
genesis plugins update <id-or-npm-spec>
genesis plugins update --all
genesis plugins marketplace list <marketplace>
genesis plugins marketplace list <marketplace> --json

Bundled plugins ship with Genesis. Some are enabled by default (for example bundled model providers, bundled speech providers, and the bundled browser plugin); others require plugins enable.

Native Genesis plugins must ship genesis.plugin.json with an inline JSON Schema (configSchema, even if empty). Compatible bundles use their own bundle manifests instead.

plugins list shows Format: genesis or Format: bundle. Verbose list/info output also shows the bundle subtype (codex, claude, or cursor) plus detected bundle capabilities.

Install

genesis plugins install <package>                      # ClawHub first, then npm
genesis plugins install clawhub:<package>              # ClawHub only
genesis plugins install <package> --force              # overwrite existing install
genesis plugins install <package> --pin                # pin version
genesis plugins install <package> --dangerously-force-unsafe-install
genesis plugins install <path>                         # local path
genesis plugins install <plugin>@<marketplace>         # marketplace
genesis plugins install <plugin> --marketplace <name>  # marketplace (explicit)
genesis plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

Bare package names are checked against ClawHub first, then npm. Security note: treat plugin installs like running code. Prefer pinned versions.

If your plugins section is backed by a single-file $include, plugins install/update/enable/disable/uninstall write through to that included file and leave genesis.json untouched. Root includes, include arrays, and includes with sibling overrides fail closed instead of flattening. See Config includes for the supported shapes.

If config is invalid, plugins install normally fails closed and tells you to run genesis doctor --fix first. The only documented exception is a narrow bundled-plugin recovery path for plugins that explicitly opt into genesis.install.allowInvalidConfigRecovery.

--force reuses the existing install target and overwrites an already-installed plugin or hook pack in place. Use it when you are intentionally reinstalling the same id from a new local path, archive, ClawHub package, or npm artifact. For routine upgrades of an already tracked npm plugin, prefer genesis plugins update <id-or-npm-spec>.

If you run plugins install for a plugin id that is already installed, Genesis stops and points you at plugins update <id-or-npm-spec> for a normal upgrade, or at plugins install <package> --force when you genuinely want to overwrite the current install from a different source.

--pin applies to npm installs only. It is not supported with --marketplace, because marketplace installs persist marketplace source metadata instead of an npm spec.

--dangerously-force-unsafe-install is a break-glass option for false positives in the built-in dangerous-code scanner. It allows the install to continue even when the built-in scanner reports critical findings, but it does not bypass plugin before_install hook policy blocks and does not bypass scan failures.

This CLI flag applies to plugin install/update flows. Gateway-backed skill dependency installs use the matching dangerouslyForceUnsafeInstall request override, while genesis skills install remains a separate ClawHub skill download/install flow.

plugins install is also the install surface for hook packs that expose genesis.hooks in package.json. Use genesis hooks for filtered hook visibility and per-hook enablement, not package installation.

Npm specs are registry-only (package name + optional exact version or dist-tag). Git/URL/file specs and semver ranges are rejected. Dependency installs run with --ignore-scripts for safety.

Bare specs and @latest stay on the stable track. If npm resolves either of those to a prerelease, Genesis stops and asks you to opt in explicitly with a prerelease tag such as @beta/@rc or an exact prerelease version such as @1.2.3-beta.4.

If a bare install spec matches a bundled plugin id (for example diffs), Genesis installs the bundled plugin directly. To install an npm package with the same name, use an explicit scoped spec (for example @scope/diffs).

Supported archives: .zip, .tgz, .tar.gz, .tar.

Claude marketplace installs are also supported.

ClawHub installs use an explicit clawhub:<package> locator:

genesis plugins install clawhub:genesis-codex-app-server
genesis plugins install clawhub:genesis-codex-app-server@1.2.3

Genesis now also prefers ClawHub for bare npm-safe plugin specs. It only falls back to npm if ClawHub does not have that package or version:

genesis plugins install genesis-codex-app-server

Genesis downloads the package archive from ClawHub, checks the advertised plugin API / minimum gateway compatibility, then installs it through the normal archive path. Recorded installs keep their ClawHub source metadata for later updates.

Use plugin@marketplace shorthand when the marketplace name exists in Claude's local registry cache at ~/.claude/plugins/known_marketplaces.json:

genesis plugins marketplace list <marketplace-name>
genesis plugins install <plugin-name>@<marketplace-name>

Use --marketplace when you want to pass the marketplace source explicitly:

genesis plugins install <plugin-name> --marketplace <marketplace-name>
genesis plugins install <plugin-name> --marketplace <owner/repo>
genesis plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
genesis plugins install <plugin-name> --marketplace ./my-marketplace

Marketplace sources can be:

a Claude known-marketplace name from ~/.claude/plugins/known_marketplaces.json
a local marketplace root or marketplace.json path
a GitHub repo shorthand such as owner/repo
a GitHub repo URL such as https://github.com/owner/repo
a git URL

For remote marketplaces loaded from GitHub or git, plugin entries must stay inside the cloned marketplace repo. Genesis accepts relative path sources from that repo and rejects HTTP(S), absolute-path, git, GitHub, and other non-path plugin sources from remote manifests.

For local paths and archives, Genesis auto-detects:

native Genesis plugins (genesis.plugin.json)
Codex-compatible bundles (.codex-plugin/plugin.json)
Claude-compatible bundles (.claude-plugin/plugin.json or the default Claude component layout)
Cursor-compatible bundles (.cursor-plugin/plugin.json)

Compatible bundles install into the normal plugin root and participate in the same list/info/enable/disable flow. Today, bundle skills, Claude command-skills, Claude settings.json defaults, Claude .lsp.json / manifest-declared lspServers defaults, Cursor command-skills, and compatible Codex hook directories are supported; other detected bundle capabilities are shown in diagnostics/info but are not yet wired into runtime execution.

List

genesis plugins list
genesis plugins list --enabled
genesis plugins list --verbose
genesis plugins list --json

Use --enabled to show only loaded plugins. Use --verbose to switch from the table view to per-plugin detail lines with source/origin/version/activation metadata. Use --json for machine-readable inventory plus registry diagnostics.

plugins list runs discovery from the current CLI environment and config. It is useful for checking whether a plugin is enabled/loadable, but it is not a live runtime probe of an already-running Gateway process. After changing plugin code, enablement, hook policy, or plugins.load.paths, restart the Gateway that serves the channel before expecting new register(api) code or hooks to run. For remote/container deployments, verify you are restarting the actual genesis gateway run child, not only a wrapper process.

For runtime hook debugging:

genesis plugins inspect <id> --json shows registered hooks and diagnostics from a module-loaded inspection pass.
genesis gateway status --deep --require-rpc confirms the reachable Gateway, service/process hints, config path, and RPC health.
Non-bundled conversation hooks (llm_input, llm_output, agent_end) require plugins.entries.<id>.hooks.allowConversationAccess=true.

Use --link to avoid copying a local directory (adds to plugins.load.paths):

genesis plugins install -l ./my-plugin

--force is not supported with --link because linked installs reuse the source path instead of copying over a managed install target.

Use --pin on npm installs to save the resolved exact spec (name@version) in plugins.installs while keeping the default behavior unpinned.

Uninstall

genesis plugins uninstall <id>
genesis plugins uninstall <id> --dry-run
genesis plugins uninstall <id> --keep-files

uninstall removes plugin records from plugins.entries, plugins.installs, the plugin allowlist, and linked plugins.load.paths entries when applicable. For active memory plugins, the memory slot resets to memory-core.

By default, uninstall also removes the plugin install directory under the active state-dir plugin root. Use --keep-files to keep files on disk.

--keep-config is supported as a deprecated alias for --keep-files.

Update

genesis plugins update <id-or-npm-spec>
genesis plugins update --all
genesis plugins update <id-or-npm-spec> --dry-run
genesis plugins update @genesis/voice-call@beta
genesis plugins update genesis-codex-app-server --dangerously-force-unsafe-install

Updates apply to tracked installs in plugins.installs and tracked hook-pack installs in hooks.internal.installs.

When you pass a plugin id, Genesis reuses the recorded install spec for that plugin. That means previously stored dist-tags such as @beta and exact pinned versions continue to be used on later update <id> runs.

For npm installs, you can also pass an explicit npm package spec with a dist-tag or exact version. Genesis resolves that package name back to the tracked plugin record, updates that installed plugin, and records the new npm spec for future id-based updates.

Passing the npm package name without a version or tag also resolves back to the tracked plugin record. Use this when a plugin was pinned to an exact version and you want to move it back to the registry's default release line.

Before a live npm update, Genesis checks the installed package version against the npm registry metadata. If the installed version and recorded artifact identity already match the resolved target, the update is skipped without downloading, reinstalling, or rewriting genesis.json.

When a stored integrity hash exists and the fetched artifact hash changes, Genesis treats that as npm artifact drift. The interactive genesis plugins update command prints the expected and actual hashes and asks for confirmation before proceeding. Non-interactive update helpers fail closed unless the caller supplies an explicit continuation policy.

--dangerously-force-unsafe-install is also available on plugins update as a break-glass override for built-in dangerous-code scan false positives during plugin updates. It still does not bypass plugin before_install policy blocks or scan-failure blocking, and it only applies to plugin updates, not hook-pack updates.

Inspect

genesis plugins inspect <id>
genesis plugins inspect <id> --json

Deep introspection for a single plugin. Shows identity, load status, source, registered capabilities, hooks, tools, commands, services, gateway methods, HTTP routes, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support.

Each plugin is classified by what it actually registers at runtime:

plain-capability — one capability type (e.g. a provider-only plugin)
hybrid-capability — multiple capability types (e.g. text + speech + images)
hook-only — only hooks, no capabilities or surfaces
non-capability — tools/commands/services but no capabilities

See Plugin shapes for more on the capability model.

The --json flag outputs a machine-readable report suitable for scripting and auditing.

inspect --all renders a fleet-wide table with shape, capability kinds, compatibility notices, bundle capabilities, and hook summary columns.

info is an alias for inspect.

Doctor

genesis plugins doctor

doctor reports plugin load errors, manifest/discovery diagnostics, and compatibility notices. When everything is clean it prints No plugin issues detected.

For module-shape failures such as missing register/activate exports, rerun with GENESIS_PLUGIN_LOAD_DEBUG=1 to include a compact export-shape summary in the diagnostic output.

Marketplace

genesis plugins marketplace list <source>
genesis plugins marketplace list <source> --json

Marketplace list accepts a local marketplace path, a marketplace.json path, a GitHub shorthand like owner/repo, a GitHub repo URL, or a git URL. --json prints the resolved source label plus the parsed marketplace manifest and plugin entries.

genesis plugins