plugin-hints.md +0 −156 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Recommend your plugin from your CLI
6
7> Emit a one-line marker from your CLI so Claude Code prompts users to install your official plugin.
8
9If you maintain a CLI or SDK and have a plugin in the official Anthropic marketplace, your tool can prompt Claude Code users to install that plugin. Your CLI writes a one-line marker to stderr when it detects it is running inside Claude Code. Claude Code reads the marker, strips it from the output, and shows the user a one-time install prompt.
10
11The protocol requires no extra commands and does not change what your CLI prints for users outside Claude Code.
12
13This page is for CLI and SDK maintainers. If you are looking to install plugins, see [Discover and install plugins](/docs/en/discover-plugins).
14
15## How it works
16
17Claude Code sets the [`CLAUDECODE`](/docs/en/env-vars) environment variable to `1` for every command it runs through the Bash and PowerShell tools, and for [hook](/docs/en/hooks) commands. From v2.1.172 it also sets [`CLAUDE_CODE_CHILD_SESSION`](/docs/en/env-vars) to `1` in those same subprocesses. When your CLI sees one of these variables, it writes a self-closing `<claude-code-hint />` tag to stderr. In hook commands the hint tag is stripped and ignored. Only Bash and PowerShell tool output triggers the install prompt.
18
19When Claude Code receives the command output, it:
20
211. Scans for hint lines and removes them before the output reaches the model
222. Checks that the hint targets a plugin in an official Anthropic marketplace
233. Checks that the plugin is not already installed and has not been prompted before
244. Shows the user an install prompt that names the command that emitted the hint
25
26Claude Code never installs a plugin automatically. The user always confirms.
27
28## Emit the hint
29
30Hint prompts only fire for plugins listed in the official Anthropic marketplace. See [Get your plugin into the official marketplace](#get-your-plugin-into-the-official-marketplace) before you ship the integration.
31
32Gate emission on an environment variable so the marker is unlikely to appear when a human runs your CLI directly, then write the tag to stderr on its own line. Choose which variable to check:
33
34* `CLAUDECODE`: set on every Claude Code version, so it reaches the most sessions. It is also set in tmux sessions and stdio MCP server subprocesses that Claude Code starts. IDE extensions also set it in their integrated terminals, where a human may be running your CLI directly.
35* `CLAUDE_CODE_CHILD_SESSION`: set only in subprocesses Claude Code itself spawns, such as tool calls, hook commands, and [status line](/docs/en/statusline) commands, so the tag does not normally reach a human terminal. A long-lived process that was started inside a session, such as a tmux server, captures the variable, so shells later launched from that process still show the raw tag.
36
37The following examples gate on `CLAUDECODE` for maximum reach and emit a hint for a plugin named `example-cli` in the official marketplace:
38
39<CodeGroup>
40 ```javascript Node.js theme={null}
41 if (process.env.CLAUDECODE) {
42 process.stderr.write(
43 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
44 )
45 }
46 ```
47
48 ```python Python theme={null}
49 import os, sys
50
51 if os.environ.get("CLAUDECODE"):
52 print(
53 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
54 file=sys.stderr,
55 )
56 ```
57
58 ```go Go theme={null}
59 if os.Getenv("CLAUDECODE") != "" {
60 fmt.Fprintln(os.Stderr,
61 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
62 }
63 ```
64
65 ```shell Shell theme={null}
66 if [ -n "$CLAUDECODE" ]; then
67 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
68 fi
69 ```
70</CodeGroup>
71
72Replace `example-cli` with your plugin's name in the official marketplace.
73
74## Choose where to emit
75
76You control which code paths emit the hint. Claude Code deduplicates by plugin, so emitting on every invocation has no downside. Touchpoints that work well include:
77
78| Placement | Why it works |
79| :------------------------ | :--------------------------------------------------------- |
80| `--help` output | Claude often runs help when exploring an unfamiliar CLI |
81| Unknown-subcommand errors | Reaches the moment Claude is confused about your interface |
82| Login or auth success | The user is already in a setup mindset |
83| First-run welcome message | A natural onboarding moment |
84
85## What the user sees
86
87When the hint passes all checks, Claude Code shows a prompt like the following:
88
89```text theme={null}
90─────────────────────────────────────────────────────────────
91 Plugin recommendation
92
93 The example-cli command suggests installing a plugin.
94
95 Plugin: example-cli
96 Marketplace: claude-plugins-official
97 Official integration for example-cli deployments
98
99 Would you like to install it?
100 ❯ 1. Yes, install example-cli
101 2. No
102 3. No, and don't show plugin installation hints again
103
104─────────────────────────────────────────────────────────────
105```
106
107The prompt names the command that produced the hint so users can spot a mismatch between the tool and the plugin it recommends. If the user doesn't respond within 30 seconds, Claude Code dismisses the prompt as **No**.
108
109Prompt frequency is bounded, and some sessions never prompt:
110
111* **Once per plugin**: after the prompt is shown, Claude Code records the plugin and never prompts for it again, regardless of the user's answer.
112* **Once per session**: across all CLIs on the machine, at most one hint prompt appears per Claude Code session.
113* **Main interactive session only**: Claude Code shows the prompt only in the terminal session the user is typing into. Claude Code never prompts for a command that a [subagent](/docs/en/sub-agents) runs, and never prompts when the user runs Claude Code in [non-interactive mode](/docs/en/headless) with the `-p` flag or through the [Agent SDK](/docs/en/agent-sdk/overview). Claude Code still strips the hint line from the command output in all of these cases.
114* **Telemetry opt-outs**: sessions where analytics are disabled never show hint prompts. This includes sessions with `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` set, and sessions on third-party providers such as Amazon Bedrock or Google Cloud's Agent Platform where the [automatic telemetry opt-out](/docs/en/data-usage#default-behaviors-by-api-provider) applies.
115
116Selecting **Yes** installs the plugin to user scope. Selecting **No, and don't show plugin installation hints again** disables all future hint prompts for the user.
117
118## Hint format
119
120The hint is a self-closing tag with three required attributes.
121
122```text theme={null}
123<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
124```
125
126| Attribute | Required | Description |
127| :-------- | :------- | :------------------------------------------------ |
128| `v` | Yes | Protocol version. `1` is the only supported value |
129| `type` | Yes | Hint kind. `plugin` is the only supported value |
130| `value` | Yes | Plugin identifier in `name@marketplace` form |
131
132Attribute values may be quoted with double quotes or left unquoted. Unquoted values cannot contain whitespace. Escape sequences are not supported.
133
134## Requirements
135
136Claude Code enforces two conditions before acting on a hint. Hints that fail either check are dropped:
137
138* **Own line**: the tag must occupy its own line. A tag embedded mid-line, for example inside a log statement, is ignored. Leading and trailing whitespace on the line is allowed.
139* **Official marketplace**: the `value` must reference a plugin in an Anthropic-controlled marketplace such as `claude-plugins-official`. Hints that point to other marketplaces are silently dropped.
140
141The hint line is always removed from the output before it reaches the model, even when the version or type is unrecognized, so the marker is never counted toward token usage.
142
143The remaining guidance is recommended but not enforced. Claude Code cannot observe whether your CLI follows it:
144
145* **Write to stderr**: stderr keeps the tag out of shell pipelines such as `example-cli deploy | jq`. Claude Code scans both streams, so stdout also works.
146* **Gate on an environment variable**: only emit when `CLAUDECODE` or `CLAUDE_CODE_CHILD_SESSION` is set. See [Emit the hint](#emit-the-hint) for how the two variables differ.
147
148## Get your plugin into the official marketplace
149
150The hint protocol only takes effect for plugins listed in the official Anthropic marketplace, `claude-plugins-official`. Anthropic curates that marketplace at its discretion, and the in-app submission forms add plugins to the [community marketplace](/docs/en/plugins#submit-your-plugin-to-the-community-marketplace) instead, which the hint protocol does not check. If you are working with an Anthropic partner contact, reach out to them to coordinate an official-marketplace listing.
151
152## See also
153
154* [Create plugins](/docs/en/plugins): build the plugin your CLI recommends
155* [Create and distribute a plugin marketplace](/docs/en/plugin-marketplaces): host plugins outside the official marketplace
156* [Environment variables](/docs/en/env-vars): full reference for `CLAUDECODE` and related variables