UI Plugin Navigation
[!NOTE]
UI plugins and UI extensions are the same thing: a sidecar-backed web
panel that renders in the auxiliary (side) pane. Treat the two terms as
interchangeable. Everything below applies whichever term the user or other
skills use.
Some plugins expose a UI panel that renders in the auxiliary (side) pane. This
skill tells you how to surface a clickable pill in chat that opens/toggles
that panel, using the sidecar:// link scheme.
When to surface a pill
Offer a pill in either situation:
- Contextual relevance. Read the enabled UI plugins'
description /
display_name. If a plugin's purpose matches what the user is doing right
now and seeing its UI would help, offer that plugin's pill.
- After a new UI plugin pane is enabled. When the user has just created
and enabled a UI plugin pane, include a pill pointing to it so they can open
it immediately.
Surface pills sparingly — only when the panel is genuinely useful. Don't repeat
a pill the user has already opened or dismissed.
Step 1: Find UI plugin panes and their views
UI plugin panes are backed by sidecars, which live under these directories (each
in its own <sidecar-id>/ folder containing a sidecar.json):
~/.gemini/config/sidecars/<sidecar-id>/
~/.gemini/<app-name>/builtin/sidecars/<sidecar-id>/
~/.gemini/config/plugins/<plugin>/sidecars/<sidecar-id>/ (or external
sidecar folders referenced by
~/.gemini/config/plugins/<plugin>/sidecars.json)
~/.gemini/<app-name>/builtin/plugins/<plugin>/sidecars/<sidecar-id>/ (or
referenced by ~/.gemini/<app-name>/builtin/plugins/<plugin>/sidecars.json)
The sidecar-id is the folder name — except for plugin sidecars (those
under a plugins/<plugin>/sidecars/ directory or referenced by a plugin's
sidecars.json), whose id is namespaced as <plugin>/<sidecar-folder>. A
sidecar has a UI panel only if its sidecar.json has has_web_ui set to true
and a ui_config.views entry with entrypoint: SIDECAR_UI_ENTRYPOINT_AUX_PANE. From that entry take:
- sidecar-id — the folder name, or
<plugin>/<folder> for plugin
sidecars.
- view-path — the
path field (e.g. /, host.html?view=auxpane).
- Use
description / display_name (and views[].title) to judge relevance
and to label the pill.
Step 2: Emit the pill link
Write a standard markdown link with the sidecar:// scheme:
[Label](sidecar://<sidecar-id>/<view-path>)
- Label — should be equivalent to the view
title, the sidecar
display_name or the sidecar_id with preference in that order. If the
sidecar is part of a plugin, you can also use the plugin name instead.
- Only emit pills for AUX_PANE views of plugins that are enabled and
running.
Examples (substitute the actual id/path you discovered in Step 1):
[<Sidecar Name>](sidecar://<sidecar-id>/)
[<Sidecar Name>](sidecar://<sidecar-id>/host.html?view=auxpane)
Constraints & Tips
- The pill toggles the aux pane. Clicking opens the plugin's panel. DO NOT
output a plugin link, if the plugin isn't enabled/running.
- Deduce relevance from the description, not guesswork. If no enabled UI
plugin's description matches the conversation, don't force a pill.
- One pill per pane. Don't emit multiple links to the same view.