ZacharyZhang-NY
d6c20fc13f
Hard fork of xai-org/grok-build (Apache-2.0) re-targeted as Kigi, an
unofficial Kimi Code CLI community build.
Rename & identity
- 72 xai-*/xai-grok-* crates -> kigi-* (explicit: xai-grok-pager-bin ->
kigi-bin [binary `kigi`], xai-grok-pager -> kigi-tui; rest mechanical);
ptyctl, ptyctl-cli, third_party/ unchanged; proto package
xai.grok.tools.v1 -> kigi.tools.v1
- Config home ~/.kigi (KIGI_SHARE_DIR override), env prefix GROK_* ->
KIGI_*, `kigi --version` carries the unofficial-community-build notice
- clap identity, help text, startup banner, prompt templates rebranded
(templates re-encrypted)
Deletions (PRD removal list #5/#6/#7/#9/#10)
- voice input (xai-grok-voice) and all TUI wiring
- telemetry: Mixpanel client, external OTel stream, Sentry, OTLP layers,
trace/GCS/S3 upload queues (kigi-file-utils halved), workspace upload
module & dc_log, heap-profile uploader, auth-diagnostics uploader,
session-analytics halves of feedback; local zero-egress observability
preserved in new kigi-log crate (unified log, --debug firehose,
subsystem file logs, opt-in instrumentation)
- announcements (crate, remote-settings fields, TUI surfaces)
- plugin marketplace (crate, sources/browse/CTA/extensions-modal tab);
direct plugin install/uninstall/update via kigi-agent git_install kept
- relay/gateway/assets endpoints and features (agent relay, headless
relay transport, gateway bridge, LeaderEnvUrls); leader IPC socket now
~/.kigi/leader.sock + KIGI_LEADER_SOCKET, no ws-url derivation
- functional types rehomed instead of deleted: PermissionMode ->
kigi-config-types, McpInitStrategy -> kigi-mcp, PrCreationSource ->
session signals, TerminalDiagnostics -> kigi-pager-render, agent_id ->
shell util
Endpoints
- kigi-env rewritten: single production KigiEndpoints {coding_api_base_url
https://api.kimi.com/coding/v1 (KIGI_CODE_BASE_URL), oauth_host
https://auth.kimi.com (KIGI_OAUTH_HOST), update_base_url (GitHub
Releases API), upgrade_page_url}; GrokBuildEnvironment enum deleted
Toolchain & workspace hygiene
- Rust 1.97.0 pinned; edition 2024; full cargo update; git2 hoisted to
workspace at 0.21 (Option->Result API migration), quick-xml 0.41
- Root Cargo.toml hand-maintained (PRD §8.1): version 0.1.0 inherited by
all members, members sorted, unused deps pruned
- cargo-deny advisories gate (deny.toml with documented transitive
exceptions); CI workflow (check/clippy/fmt/deny/test, macOS+Linux)
- cross-crate test seams re-gated behind `test-support` cargo feature;
insta snapshot baselines renamed to the kigi_tui prefix
- clippy --workspace --all-targets: zero warnings; fmt clean
Fixes surfaced by the port
- updater probe/installer divergence (bin/kigi vs bin/grok symlink set)
- idle model-metadata refresh dead under KIGI_CODE_BASE_URL override
(new is_effective_coding_endpoint_url, loopback+override aware)
- macOS symlinked-TMPDIR fixture canonicalization (foreign_sessions,
fast-worktree); RSS measurement tests serialized via serial_test
Docs & legal (Apache §4)
- NOTICE added (upstream attribution + change statement); THIRD-PARTY
notices sustained; kigi-tools ported-code notices extended; README,
CONTRIBUTING, SECURITY, AGENTS.md rewritten
Out of scope for M0 (tracked): Kimi auth/inference (M1), search/fetch,
command parity, config import (M2), Computer Hub excision & final
brand-token sweep (M2), distribution & self-update rewrite (M3).
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, 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 |
|
||
|----------------------|-------------|
|
||
| `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. |
|
||
|
||
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 |
|
||
| `.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 |
|
||
|
||
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 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
|
||
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
|
||
|
||
### 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.
|
||
|
||
Grok trusts plugins from `~/.kigi/plugins/` automatically. Project plugins in `.kigi/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.
|