Publish harness and TUI open-source
initial sync from the monorepo
This commit is contained in:
grokkybara[bot]
commit
c68e39f604
2734 changed files with 1437016 additions and 0 deletions
273
crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md
Normal file
273
crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
# Plugins
|
||||
|
||||
A plugin bundles skills, slash commands, agents, hooks, MCP server configurations, and LSP server configurations into one installable unit.
|
||||
|
||||
---
|
||||
|
||||
## What a plugin contains
|
||||
|
||||
A plugin is a directory that holds any combination of these components:
|
||||
|
||||
- **Skills** -- a `skills/` directory of SKILL.md files
|
||||
- **Slash commands** -- a `commands/` directory of command files
|
||||
- **Agents** -- an `agents/` directory of agent definitions
|
||||
- **Hooks** -- a `hooks/hooks.json` file of lifecycle hooks. Plugin hooks also receive `GROK_PLUGIN_ROOT` and `GROK_PLUGIN_DATA` (see the [Hooks guide](10-hooks.md) for every environment variable passed to hooks).
|
||||
- **MCP servers** -- a `.mcp.json` file of server configurations
|
||||
- **LSP servers** -- a `.lsp.json` file of language server configurations
|
||||
|
||||
If a plugin includes a `plugin.json` manifest, the manifest can override paths or add metadata; otherwise components load from the convention directories. The manifest is optional: without one, Grok discovers the components above from their standard directories.
|
||||
|
||||
For example, a `team-tools` plugin might include a deploy skill, a code-review agent, pre-commit hooks, and a Linear MCP server. Install them together in one step.
|
||||
|
||||
## Environment variables in plugin hooks
|
||||
|
||||
Plugin hooks receive two environment variables beyond the standard ones set for every hook:
|
||||
|
||||
| Variable | Description |
|
||||
|----------------------|-------------|
|
||||
| `GROK_PLUGIN_ROOT` | Absolute path to the plugin's installed directory. |
|
||||
| `GROK_PLUGIN_DATA` | Absolute path to the plugin's writable data directory, for plugin state, caches, and logs. |
|
||||
|
||||
Grok sets these values and overrides any value you declare for the same key in the hook JSON's `env` map. (Grok also sets the `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` aliases for compatibility.) See the [Hooks guide](10-hooks.md) for every environment variable passed to hooks.
|
||||
|
||||
---
|
||||
|
||||
## Plugin locations
|
||||
|
||||
Grok discovers plugins from these locations, in priority order:
|
||||
|
||||
| Location | Scope | Trust |
|
||||
|----------|-------|-------|
|
||||
| `_meta.pluginDirs` (`session/new` / `session/load`) | Session -- loaded for that session only | Trusted automatically |
|
||||
| `--plugin-dir` (CLI flag, `grok agent`) | Process -- loaded for that agent process only | Trusted automatically |
|
||||
| `.grok/plugins/` | Project -- shared with the team through version control | Requires trust |
|
||||
| `~/.grok/plugins/` | User -- personal plugins for every project | Trusted automatically |
|
||||
| `[plugins].paths` (config) | Custom directories you add in `config.toml` | Depends on location |
|
||||
|
||||
Grok also reads the `.claude/plugins/` equivalents for compatibility. When two plugins share a name, the higher-priority location wins.
|
||||
|
||||
The Agent SDKs load per-session plugins through `GrokOptions.plugins`, which arrives as `_meta.pluginDirs` on `session/new` and `session/load`; because the caller controls the directory, these plugins are always trusted -- their hooks and MCP servers activate without a prompt, and they never persist beyond the session. The `--plugin-dir` flag is the process-wide equivalent for direct CLI use (repeatable: `grok agent --no-leader --plugin-dir A --plugin-dir B stdio`); it applies to dedicated agent processes only and is ignored in leader mode (the shared leader discovers its own plugins).
|
||||
|
||||
---
|
||||
|
||||
## Manage plugins in the TUI
|
||||
|
||||
### Open the modal
|
||||
|
||||
| Action | Opens |
|
||||
|--------|-------|
|
||||
| `Ctrl+L` (from any pane; **non–VS Code family**) | Plugins tab |
|
||||
| `/plugins` (any terminal; **required on VS Code family**) | Plugins tab |
|
||||
|
||||
The modal has five tabs: **Hooks**, **Plugins**, **Marketplace**, **Skills**, and **MCP Servers**. Switch tabs with `Tab` (forward) or `Shift+Tab` (backward). The `/hooks`, `/marketplace`, `/skills`, and `/mcps` commands each open the modal on the matching tab.
|
||||
|
||||
### Plugins tab
|
||||
|
||||
Press `Enter` to expand a plugin row and show its details:
|
||||
|
||||
- **Name** and **version**
|
||||
- **Scope** -- `cli`, `project`, `user`, `custom path`, or the marketplace source name
|
||||
- **Skills** -- names or count
|
||||
- **Agents** -- names or count
|
||||
- **Hooks** -- count
|
||||
- **MCP servers** -- count (or `blocked` when the plugin is not trusted)
|
||||
- **Description** and **path**
|
||||
|
||||
Use these keys in the Plugins tab:
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `r` | Reload all plugins |
|
||||
| `a` | Add a plugin from `owner/repo`, a URL, or a local path |
|
||||
| `Space` | Enable or disable the selected plugin |
|
||||
| `x` | Uninstall the selected plugin |
|
||||
| `f` | Filter by status (all, enabled, or disabled) |
|
||||
| `Enter` | Expand or collapse plugin details |
|
||||
| `/` | Search plugins by name |
|
||||
|
||||
### Marketplace tab
|
||||
|
||||
Browse and install plugins from your configured marketplace sources.
|
||||
|
||||
Use these keys in the Marketplace tab:
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `i` | Install the selected plugin |
|
||||
| `d` | Uninstall the selected plugin |
|
||||
| `a` | Add a marketplace source |
|
||||
| `x` | Remove the selected source and its plugins |
|
||||
| `r` | Refresh marketplace sources |
|
||||
| `u` | Update the selected marketplace plugin |
|
||||
| `Enter` | Expand or collapse a source or plugin |
|
||||
| `/` | Search plugins by name |
|
||||
|
||||
Component summaries on list rows and per-category component details in the
|
||||
expanded view appear only for marketplaces that publish a `plugin-index.json`
|
||||
catalog.
|
||||
|
||||
---
|
||||
|
||||
## CLI commands
|
||||
|
||||
Manage plugins without starting an interactive session.
|
||||
|
||||
### Plugin commands
|
||||
|
||||
```bash
|
||||
grok plugin list [--json] [--available] # List installed plugins (--available requires --json)
|
||||
grok plugin install <source> --trust # Git URL, GitHub shorthand (user/repo), or local path
|
||||
grok plugin uninstall <name> [--confirm] [--keep-data] # Aliases: rm, remove
|
||||
grok plugin update [<name>] # Omit the name to update all plugins
|
||||
grok plugin enable <name>
|
||||
grok plugin disable <name>
|
||||
grok plugin details <name> # Show the plugin's component inventory
|
||||
grok plugin validate [<path>] # Validate plugin.json (default: current directory)
|
||||
grok plugin tag [<path>] [--push] [--force] [--dry-run] # Tag a release from the manifest version
|
||||
```
|
||||
|
||||
Run `grok plugin install <source>` without `--trust` and Grok prints the source and warns that installing will activate the plugin's hooks, MCP servers, and skills, then stops without installing. Add `--trust` to install it.
|
||||
|
||||
The `<source>` argument accepts:
|
||||
|
||||
- `user/repo` -- GitHub shorthand
|
||||
- `user/repo@v1.0` -- pinned to a ref
|
||||
- `user/repo#subdir` -- subdirectory within the repo
|
||||
- `https://github.com/user/repo.git` -- full URL
|
||||
- `git@github.com:user/repo.git` -- SSH
|
||||
- `./local-dir` or `/absolute/path` -- local directory
|
||||
|
||||
### Marketplace commands
|
||||
|
||||
```bash
|
||||
grok plugin marketplace list [--json]
|
||||
grok plugin marketplace add <url> # Git URL, GitHub shorthand (user/repo), or local path
|
||||
grok plugin marketplace remove <url> # Git URL or local path of a configured source
|
||||
grok plugin marketplace update [<name>] # Omit the name to refresh all sources
|
||||
```
|
||||
|
||||
### Example: set up a team marketplace
|
||||
|
||||
```bash
|
||||
grok plugin marketplace add my-org/team-plugins
|
||||
grok plugin marketplace list
|
||||
grok plugin install my-org/team-plugins --trust
|
||||
grok plugin list
|
||||
grok plugin update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Slash commands
|
||||
|
||||
In an interactive session, these commands open the modal on a specific tab. They take no arguments — manage plugins from the modal or with the `grok plugin` CLI.
|
||||
|
||||
| Command | Opens |
|
||||
|---------|-------|
|
||||
| `/plugins` | Plugins tab |
|
||||
| `/hooks` | Hooks tab |
|
||||
| `/marketplace` | Marketplace tab |
|
||||
| `/skills` | Skills tab |
|
||||
| `/mcps` | MCP Servers tab |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure plugin directories and per-plugin state in `~/.grok/config.toml`:
|
||||
|
||||
```toml
|
||||
[plugins]
|
||||
paths = ["~/my-plugins/custom-tools"] # Additional plugin directories
|
||||
disabled = ["user/a1b2c3d4/noisy-plugin"] # Plugin IDs or names to skip
|
||||
enabled = ["project/9f8e7d6c/team-tools"] # Plugin IDs or names to force on
|
||||
```
|
||||
|
||||
List a plugin in `disabled` to discover it but skip loading its components. List a plugin in `enabled` to activate it — plugins are disabled by default unless a CLI override or an explicit config path enables them, so add them here to turn them on. Each entry is either a plain plugin name (as shown by `grok plugin list`) or a full plugin ID in the form `<scope>/<hash>/<name>`.
|
||||
|
||||
### Hide the plugins UI
|
||||
|
||||
To hide the hooks and plugins UI — the `/hooks` and `/plugins` commands and the scrollback annotations — set this in `~/.grok/pager.toml`:
|
||||
|
||||
```toml
|
||||
disable_plugins = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Marketplace sources
|
||||
|
||||
Add git or local marketplace sources to discover and install plugins.
|
||||
|
||||
### In config.toml
|
||||
|
||||
Each source needs a `name` and either a `git` URL (with an optional `branch`) or a local `path`:
|
||||
|
||||
```toml
|
||||
[[marketplace.sources]]
|
||||
name = "My Team Plugins"
|
||||
git = "https://github.com/my-org/plugins.git"
|
||||
|
||||
[[marketplace.sources]]
|
||||
name = "Local Dev"
|
||||
path = "~/dev/my-plugins"
|
||||
```
|
||||
|
||||
### In settings.json
|
||||
|
||||
Add sources under `extraKnownMarketplaces`, keyed by name. Each entry's `source` is one of `git` (with `url`), `github` (with `repo`), or `local` (with `path`):
|
||||
|
||||
```json
|
||||
{
|
||||
"extraKnownMarketplaces": {
|
||||
"my-marketplace": {
|
||||
"source": { "source": "git", "url": "git@github.com:my-org/plugins.git" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Place this file at `~/.grok/settings.json` or `~/.claude/settings.json`.
|
||||
|
||||
---
|
||||
|
||||
## Trust model
|
||||
|
||||
Enabling a plugin loads its skills, slash commands, and agents. Trust is separate and controls whether a plugin's code runs: even for an enabled plugin, its hooks, MCP servers, and LSP servers stay inactive until you trust it. This prevents an untrusted repository from running code on your machine.
|
||||
|
||||
Grok trusts plugins from `~/.grok/plugins/` automatically. Project plugins in `.grok/plugins/` require explicit trust. To trust a plugin, install it with `--trust`:
|
||||
|
||||
```bash
|
||||
grok plugin install <source> --trust
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inspect plugins
|
||||
|
||||
Run `grok inspect` to see every discovered plugin and what it provides:
|
||||
|
||||
```bash
|
||||
grok inspect # Show plugins with their skills, agents, hooks, and MCP servers
|
||||
grok inspect --json # Emit machine-readable JSON
|
||||
```
|
||||
|
||||
Plugin-provided components appear in their sections (Skills, Agents, MCP Servers, and so on) with a `plugin: <name>` label, so you can see where each component originates.
|
||||
|
||||
---
|
||||
|
||||
## General keyboard shortcuts
|
||||
|
||||
These keys work across every tab in the modal:
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Tab` | Next tab |
|
||||
| `Shift+Tab` | Previous tab |
|
||||
| `j` / down-arrow | Move selection down |
|
||||
| `k` / up-arrow | Move selection up |
|
||||
| `Enter` | Expand or collapse the selected item |
|
||||
| `/` | Search the current tab by name |
|
||||
| `Esc` | Clear the search, or close the modal |
|
||||
|
||||
Some actions, such as uninstalling a plugin, ask for confirmation. Press `y` to confirm or `Esc` to cancel.
|
||||
Loading…
Reference in a new issue