| 1 | # Installing plugins |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/PLUGINS.md](zh_hans/PLUGINS.md)。 |
| 4 | |
| 5 | To create a bundle, start with [Write your first Codewhale plugin](PLUGIN_AUTHORING.md) |
| 6 | and its runnable Skills example. |
| 7 | |
| 8 | This is the walkthrough for the `/plugin install` on-ramp (v0.9.4, #5182). |
| 9 | [PLUGIN_BUNDLES.md](PLUGIN_BUNDLES.md) remains the contract for the bundle |
| 10 | format (`plugin.json`, compatible `kimi.plugin.json` or |
| 11 | `.claude-plugin/plugin.json`, or legacy `plugin.toml`), discovery, validation, and |
| 12 | the trust/enable lifecycle — this document covers how bits get onto disk in |
| 13 | the first place. |
| 14 | |
| 15 | `/plugin suggest <task>` is a local, read-only companion: it ranks already |
| 16 | installed bundles (name, keywords, description, bundled skill names, declared |
| 17 | hosts) and any marketplace catalogs you have added with `/plugin marketplace add`. |
| 18 | It explains the match and gives the next review, enable, or catalog-install |
| 19 | step, but never installs, trusts, or enables a bundle on its own. |
| 20 | |
| 21 | ## How Codewhale offers plugins |
| 22 | |
| 23 | Codewhale is helpful about plugins, not pushy. The rules: |
| 24 | |
| 25 | - **One proactive surface.** Sending a task can show one quiet toast when the |
| 26 | prompt matches an installed-but-idle plugin or a catalog candidate you do |
| 27 | not have yet, for example `/plugin trust supabase` or |
| 28 | `/plugin marketplace install <catalog> supabase`. Nothing appears while you |
| 29 | type, and nothing is appended to your message to advertise plugins. |
| 30 | - **One switch.** With `contextual_tips` off, no plugin guidance appears |
| 31 | anywhere. Required notices and your own `/plugin` commands still work. |
| 32 | - **One budget.** Plugin offers share the per-session guidance budget with |
| 33 | other tips. In the interactive TUI the model can call |
| 34 | `request_plugin_install` once per session to ask you to review a plugin the |
| 35 | task needs; a second call fails. Exec, ACP, and runtime-API sessions do not |
| 36 | get the tool. |
| 37 | - **Built-ins are never advertised.** Bundled plugins such as Computer Use |
| 38 | appear only in `/plugin list` and Extensions. |
| 39 | - **Specific terms only.** Generic words (accessibility, browser, chrome, |
| 40 | docs, screenshot, web, wiki, …) never trigger an offer. The matcher and the |
| 41 | marketplace's `check-marketplace.mjs` share one stoplist. |
| 42 | - **Only what runs here.** Plugins whose `when.os` excludes this OS are not |
| 43 | offered. |
| 44 | - **Review before acting.** A model-requested row offers Review. Its button |
| 45 | opens the existing Extensions inventory: Plugins for an installed bundle, |
| 46 | Marketplace for a suggestion that is not installed. Nothing is installed, |
| 47 | trusted, or enabled by that click. Choose the inventory's explicit action; |
| 48 | trust still reviews the exact installed content before activation. |
| 49 | - **Reversible dismissal.** Esc clears a non-empty draft first, then hides the |
| 50 | row for this session only. "Don't suggest again" is the explicit, |
| 51 | persisted choice. `/plugin dismissals` lists both kinds, and |
| 52 | `/plugin dismissals reset [<name>]` lets suggestions offer a plugin again. |
| 53 | - **Discovery is passive.** Find new plugins in these docs, |
| 54 | `/plugin marketplace list`, Extensions, and the browser guide below. |
| 55 | |
| 56 | Codewhale does not invent a remote plugin URL; missing plugins are suggested |
| 57 | only from catalogs you added. On-disk bundle changes still toast |
| 58 | `/plugin reload` on send and between turns. |
| 59 | |
| 60 | ## Browser: pick one |
| 61 | |
| 62 | Several options can drive a browser. They differ in whose browser it is and |
| 63 | what it can see. |
| 64 | |
| 65 | | Option | Whose browser | Good for | |
| 66 | | --- | --- | --- | |
| 67 | | `chrome-devtools` MCP (`/mcp recommendations`) | A Chrome it drives, which can include signed-in pages | DevTools-level inspection and performance work | |
| 68 | | Playwright MCP (`/mcp recommendations`) | A fresh, isolated profile with `--isolated` | Scripted flows and testing without your identity | |
| 69 | | Computer Use `browser_*` tools (bundled, off until reviewed) | One it launches, in a profile of its own | Browser steps inside a wider desktop task | |
| 70 | | Chromewhale (developer preview, `codewhale-hq/codewhale-plugin-marketplace`) | Yours, already open, in your own Chrome profile; load unpacked | Reading or acting on the tab you are looking at, one granted site at a time | |
| 71 | |
| 72 | None of these is offered to you proactively. Add the one that fits the job. |
| 73 | |
| 74 | ## Sources |
| 75 | |
| 76 | `/plugin install <spec>` accepts three source kinds: |
| 77 | |
| 78 | ```text |
| 79 | /plugin install ./path/to/bundle # local directory (copied) |
| 80 | /plugin install github:owner/repo # GitHub archive of the default branch |
| 81 | /plugin install https://example.com/x.tar.gz # direct tarball URL |
| 82 | ``` |
| 83 | |
| 84 | There is no registry index and no `git clone` in v1 — tarball-only fetching |
| 85 | keeps the size cap and no-symlink guarantees of the installer. Downloads are |
| 86 | gated by the per-domain network policy: an unknown host returns a |
| 87 | "needs approval" error naming the host (`/network allow <host>`, then retry), |
| 88 | a denied host aborts without touching disk. |
| 89 | |
| 90 | The fetched tree must contain **exactly one** bundle root — a directory |
| 91 | holding a `plugin.json`, compatible `kimi.plugin.json`, |
| 92 | `.claude-plugin/plugin.json`, or legacy `plugin.toml` manifest. Kimi bundles are accepted when they use Codewhale-compatible Skills, |
| 93 | commands, agents, and MCP declarations; unsupported Kimi runtime fields fail |
| 94 | closed instead of being silently ignored. Bundles land in |
| 95 | the user plugins root at `~/.codewhale/plugins/<name>/`, where `<name>` is the |
| 96 | manifest's plugin name. |
| 97 | |
| 98 | Claude bundles keep their metadata in `.claude-plugin/plugin.json` and their |
| 99 | components at the bundle root. The importer supports skills, commands, agents, |
| 100 | and MCP servers declared inline or in root `.mcp.json` (flat server map or an |
| 101 | `mcpServers` wrapper). Claude `http` transport maps to Streamable HTTP. Relative |
| 102 | sources in a `.claude-plugin/marketplace.json` catalog resolve from the marketplace |
| 103 | repository root. The whole bundle remains subject to the same review hashes and |
| 104 | path checks as native plugins. |
| 105 | |
| 106 | Remote MCP headers can name credentials without embedding them: exact |
| 107 | `Bearer ${ENV_NAME}` authorization values become `bearer_token_env_var`, and |
| 108 | exact `${ENV_NAME}` header values become `env_headers`. Import reads no credential |
| 109 | values. Literal credentials and compound templates are rejected. |
| 110 | |
| 111 | This is a compatible subset: hooks, LSP declarations, custom MCP file paths, and |
| 112 | `${CLAUDE_PLUGIN_ROOT}` expansion are rejected with an explanation; no partial |
| 113 | plugin is installed. Installing a remote MCP declaration does not complete its |
| 114 | authentication. Plugin-contributed remote servers retain the existing explicit |
| 115 | credential requirements; this importer does not enable plugin OAuth. |
| 116 | |
| 117 | ## The guided flow |
| 118 | |
| 119 | Installing never activates anything. The command places the bits, then drops |
| 120 | you straight into the standard capability review: |
| 121 | |
| 122 | ```text |
| 123 | /plugin install github:someone/neat-plugin |
| 124 | → Installed plugin 'neat-plugin' to ~/.codewhale/plugins/neat-plugin. |
| 125 | It is disabled and untrusted. Review its requested authority below… |
| 126 | <full inventory, permissions, MCP authority render> |
| 127 | /plugin trust neat-plugin <content-hash>.<capability-hash> |
| 128 | |
| 129 | /plugin trust neat-plugin <paste the token> # records the hash-bound receipt |
| 130 | /plugin enable neat-plugin # activates for this workspace |
| 131 | ``` |
| 132 | |
| 133 | This is the same review render and confirmation token as `/plugin trust |
| 134 | <name>` — trust is the strict hash-bound receipt flow, not an advisory marker. |
| 135 | If the bundle's content or declared capabilities change, the receipt stops |
| 136 | matching and the plugin goes inactive until you review again. |
| 137 | |
| 138 | ## Update and uninstall |
| 139 | |
| 140 | ```text |
| 141 | /plugin update <name> # re-download, byte-compare, atomic swap if changed |
| 142 | /plugin disable <name> # required before uninstall |
| 143 | /plugin uninstall <name> # deletes the bundle and prunes its state entry |
| 144 | ``` |
| 145 | |
| 146 | - `update` re-downloads the recorded source. Identical bytes are a no-op; a |
| 147 | changed bundle is swapped atomically and its trust receipt is automatically |
| 148 | invalidated (the hash no longer matches), so re-review is forced before the |
| 149 | plugin can activate again. Plugins installed from a local path cannot be |
| 150 | re-downloaded. To replace their installed copy, disable and uninstall it, |
| 151 | then run `/plugin install <path>` and review the new bundle; the original |
| 152 | source directory is left intact. See the [local authoring loop](PLUGIN_AUTHORING.md#4-iterate-and-review-changes). |
| 153 | - `uninstall` refuses enabled plugins (disable first), deletes the bundle |
| 154 | directory, and removes its persisted trust/enablement entry. |
| 155 | |
| 156 | ## Safety rules |
| 157 | |
| 158 | - Every install carries an `.installed-from` provenance marker. The installer |
| 159 | **refuses to overwrite or delete** a bundle that lacks it — hand-placed |
| 160 | bundles under `~/.codewhale/plugins/` are never clobbered. |
| 161 | - Tarballs are size-capped and extracted into a private staging directory |
| 162 | first; path traversal (`..`, absolute paths) and symlinks/hard links inside |
| 163 | the bundle are rejected, and the destination only appears via an atomic |
| 164 | rename after every check passes. |
| 165 | - Install pre-checks the name against builtin and workspace bundles so a |
| 166 | higher-precedence bundle cannot silently shadow (or be shadowed by) the |
| 167 | install. |
| 168 | - Newly installed bits are always **disabled and untrusted**; enablement only |
| 169 | ever happens through the explicit trust review above. |
| 170 |