ZacharyZhang-NY
6f31415ed6
The PRD's first acceptance gate now holds: grep -RinE '\bx\.ai\b|grok' crates/ --include='*.rs' → 0 matches (exempt: NOTICE and third-party license archives, README provenance, and the required 'Based on Grok Build Open Source' attribution, now sourced from version_attribution.txt). Wire-visible renames (both sides in this repo, changed in lockstep): - Auth method id 'grok.com' → 'kimi-code' (AuthMethodKind::KimiCode). - Every x.ai/* and _x.ai/* ACP ext method and meta key → kigi/* / _kigi/* (~200 names; grokShell → kigiShell). Session-file replay keeps a read-side alias for the legacy '_x.ai/session/update' method so existing updates.jsonl histories load; writes emit only the new name (both directions test-pinned). - Agent types grok-build* → kigi* with a documented legacy-prefix alias at resolution time so persisted sessions keep resolving. - ToolNamespace/BuiltinAgentName GrokBuild* → Kigi* (wire snake_case kigi/kigi_concise/kigi_hashline; schema regenerated); grok_build implementation dirs renamed to kigi*. - x-grok-* headers → x-kigi-*, __GROK_* sentinels → __KIGI_*, themes grokday/groknight → kigiday/kiginight (old persisted values fall back to the default theme), web_fetch allowlist xAI hosts → kimi.com + moonshot platforms, changelog CDN → this repo, grok-build changelog archives deleted. - BYOK default endpoint removed: [endpoints] api_base_url is now truly optional with NO default — consumers fail fast with the flag name when unset (no silent x.ai egress). Mock harnesses inject it explicitly. - System-prompt identity fixed: 'released by xAI' → 'an unofficial community CLI for Kimi' (template + regenerated encrypted form). Also repaired pre-existing grok-era test debt found by the sweep: the stale trace_classify default-model pin, the grok-pager UA label test, pty-harness stale-binary reuse and non-hermetic moonshot routing (a PTY test could previously reach the real api.moonshot.cn), and the outdated oauth fixture scope key. Gates: §9 grep 0; fmt clean; workspace check/clippy 0/0 (-D warnings); FULL cargo test --workspace: 234 suites, 21,961 passed, 0 failed; deny advisories ok.
163 lines
7.3 KiB
Markdown
163 lines
7.3 KiB
Markdown
# 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 `KIGI_PLUGIN_ROOT` and `KIGI_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, Kigi 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 |
|
||
|----------------------|-------------|
|
||
| `KIGI_PLUGIN_ROOT` | Absolute path to the plugin's installed directory. |
|
||
| `KIGI_PLUGIN_DATA` | Absolute path to the plugin's writable data directory, for plugin state, caches, and logs. |
|
||
|
||
Kigi sets these values and overrides any value you declare for the same key in the hook JSON's `env` map. (Kigi 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
|
||
|
||
Kigi 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, `kigi agent`) | Process -- loaded for that agent process only | Trusted automatically |
|
||
| `.kigi/plugins/` | Project -- shared with the team through version control | Requires trust |
|
||
| `~/.kigi/plugins/` | User -- personal plugins for every project | Trusted automatically |
|
||
| `[plugins].paths` (config) | Custom directories you add in `config.toml` | Depends on location |
|
||
|
||
Kigi 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 `KigiOptions.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: `kigi 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 four tabs: **Hooks**, **Plugins**, **Skills**, and **MCP Servers**. Switch tabs with `Tab` (forward) or `Shift+Tab` (backward). The `/hooks`, `/plugins`, `/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`, or `custom path`
|
||
- **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 |
|
||
|
||
### Plugin commands
|
||
|
||
```bash
|
||
kigi plugin list [--json] [--available] # List installed plugins (--available requires --json)
|
||
kigi plugin install <source> --trust # Git URL, GitHub shorthand (user/repo), or local path
|
||
kigi plugin uninstall <name> [--confirm] [--keep-data] # Aliases: rm, remove
|
||
kigi plugin update [<name>] # Omit the name to update all plugins
|
||
kigi plugin enable <name>
|
||
kigi plugin disable <name>
|
||
kigi plugin details <name> # Show the plugin's component inventory
|
||
kigi plugin validate [<path>] # Validate plugin.json (default: current directory)
|
||
kigi plugin tag [<path>] [--push] [--force] [--dry-run] # Tag a release from the manifest version
|
||
```
|
||
|
||
Run `kigi plugin install <source>` without `--trust` and Kigi 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
|
||
|
||
### Hide the plugins UI
|
||
|
||
To hide the hooks and plugins UI — the `/hooks` and `/plugins` commands and the scrollback annotations — set this in `~/.kigi/pager.toml`:
|
||
|
||
```toml
|
||
disable_plugins = true
|
||
```
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
Kigi trusts plugins from `~/.kigi/plugins/` automatically. Project plugins in `.kigi/plugins/` require explicit trust. To trust a plugin, install it with `--trust`:
|
||
|
||
```bash
|
||
kigi plugin install <source> --trust
|
||
```
|
||
|
||
---
|
||
|
||
## Inspect plugins
|
||
|
||
Run `kigi inspect` to see every discovered plugin and what it provides:
|
||
|
||
```bash
|
||
kigi inspect # Show plugins with their skills, agents, hooks, and MCP servers
|
||
kigi 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.
|