Opening links in a plugin (link claims)

What it is

• Some plugins can show things you are sent links to, such as the GitHub plugin showing a pull request or an issue.
• With this switched on, clicking such a link opens it in the plugin instead of a browser tab, so you stay in Omniscio.
• It is off for every plugin until you turn it on, including after an update, and an AI agent cannot turn it on for you.

Where to find it

• Settings → Plugins, on the plugin's card: expand its settings and turn on Open links in this plugin.
• The switch lists the exact link shapes the plugin opens, such as github.com/{owner}/{repo}/pull/{n}.
• It only appears for a plugin that declares link shapes.

How it behaves

• Plain click on a matching link in session output, an operator or system message, or Team Chat: the plugin opens the item and its panel comes to the front. A short "Opening in …" notice shows while it works.
• Ctrl, Cmd, Shift, Alt or middle click, or right-click → Open in browser: your browser, always.
• The plugin cannot open it (not signed in, cannot read it, not found, not running, no answer in 10 seconds): your browser opens instead, with a one-line note saying why.
• Two plugins claim the same link: neither gets it; your browser opens.
• Never claimed: links in code, links in third-party text such as a marketplace README, shortened or redirecting links (for example git.io), plain http:// links, and any page that does not match a claimed shape exactly.
• On the phone: links behave as they always did.

For agents

• Manifest: linkClaims: [{ "host": "github.com", "path": "/{owner}/{repo}/pull/{n}" }]. host is one exact lowercase domain with no wildcard, port or user name; path is literal segments plus {name} placeholders (one segment each) with at least one literal. A wider claim fails manifest validation.
• Route: declare { "method": "POST", "path": "open-link", "safe": true } in cli.endpoints and register it with ctx.cli.handle('open-link', …). Without a safe POST open-link, the app never calls the plugin.
• Request: the body is exactly { "url": "<the clicked link>" }, query and # anchor included. Re-parse it; never assume the app matched it.
• Reply: { "opened": true } once the item is queued or shown, or { "opened": false, "message": "<one plain sentence>" }. The message is shown as plain text on one line, cut to 200 characters; any other field is ignored, and opened: true only brings your own panel forward.
• Host side: setting pluginsOpeningLinks (plugin ids; refused to agent session tokens), IPC plugin:open-link (desktop only, blocked on the phone bridge). Rules: the plugin link claims contract in .claude/memory/contracts/plugin-link-claim-contract.md.

Related

• The plugin marketplace page explains installing and enabling plugins, which a plugin must be before it can claim a link.
• Plugin CLI discovery covers the same plugin action door the link hand-off uses.