Adding Plugin Install Hints to Developer CLIs

Overview

If you maintain a CLI or SDK and have a plugin in the official Anthropic marketplace, your tool can prompt Claude Code users to install it. 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 a one-time install prompt. The user always confirms; nothing installs automatically.

How it works

Claude Code sets the CLAUDECODE environment variable to 1 for commands it runs through the Bash and PowerShell tools. When your CLI sees that variable, it writes a self-closing <claude-code-hint /> tag to stderr. Claude Code then:

1. Scans for hint lines and removes them before output reaches the model.
2. Checks the hint targets a plugin in an official Anthropic marketplace.
3. Checks the plugin is not already installed and has not been prompted before.
4. Shows an install prompt naming the command that emitted the hint.

Emit the hint

Gate on CLAUDECODE and write the tag on its own line:

// Node.js
if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}

# Python
import os, sys
if os.environ.get("CLAUDECODE"):
    print(
        '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
        file=sys.stderr,
    )

Replace example-cli with your plugin's name in the official marketplace.

Hint format

<claude-code-hint v="1" type="plugin" value="name@marketplace" />

Where to emit

Claude Code deduplicates by plugin, so emitting on every invocation is fine. Good touchpoints: --help output, unknown-subcommand errors, login/auth success, and first-run welcome messages.

What the user sees

Claude Code shows a one-time prompt naming the command, with options to install, decline, or disable future hints. Frequency is bounded: once per plugin, and at most one hint prompt per Claude Code session across all CLIs. If there is no response within 30 seconds, it dismisses as No.

Requirements

• The tag must occupy its own line; mid-line tags are ignored.
• The value must reference a plugin in an official Anthropic marketplace such as claude-plugins-official; other marketplaces are silently dropped.
• Recommended: write to stderr and gate on CLAUDECODE.

The hint protocol only takes effect for plugins listed in the official Anthropic marketplace, which Anthropic curates at its discretion. The community-marketplace submission form does not enable the hint protocol.

Source

• Recommend your plugin from your CLI: https://code.claude.com/docs/en/plugin-hints