kibi-cursor
v2.15.0
Published
Kibi Cursor plugin - thin adapter for Cursor MCP integration and editor hooks
Readme
kibi-cursor
Cursor plugin for Kibi — repo-local, per-branch, queryable knowledge base.
kibi-cursor is optional. It provides Cursor-specific rules, skills, commands, MCP wiring, and advisory editor hooks, but it does not ship a replacement kibi CLI or kibi-mcp server binary.
Prerequisites
Install these before enabling the plugin MCP server:
| Requirement | Why |
| --- | --- |
| SWI-Prolog 9+ | Powers Kibi inference and validation. Bundled with kibi-cli on Linux (x64, arm64) and macOS; install it with swipl on PATH only on other platforms |
| kibi-cli | Project CLI (kibi command) |
| kibi-mcp | MCP server installed in the opened project; the plugin launcher resolves this package without downloading it |
| kibi-core | Shared graph/runtime dependency |
npm install --save-dev kibi-cli kibi-mcp kibi-core
npm exec -- kibi doctorFull setup: installation guide.
Add this plugin only after the base packages work in your project.
Git worktrees: the published plugin MCP entry resolves kibi-mcp from the opened worktree's node_modules (run install there). The plugin does not download or bundle a Kibi runtime. For this monorepo's dogfood path, prefer project .cursor/mcp.json, which can fall back to the primary checkout's built MCP — see DEV.md.
Installation
Cursor Marketplace (recommended)
Submit or install from the Kibi repository marketplace at .cursor-plugin/marketplace.json, which points at ./plugins/kibi-cursor (Cursor Plugin) and ./plugins/kibi-agent-plugin (portable Agent Plugin). Cursor detects the format from the plugin manifest, so both install from the same marketplace.
For local testing before marketplace publication, copy a real directory tree into Cursor's user-plugins folder. Symlinks are rejected when the target lives outside plugins/local (common on WSL):
./scripts/sync-cursor-plugin-local.shOn WSL workspaces, Cursor reads ~/.cursor/plugins/local in your Linux home, not the Windows profile path. Reload Cursor (Developer: Reload Window) and check Plugins → User.
npm package
npm install --save-dev kibi-cursorCopy the installed package into Cursor's local plugin directory (do not
symlink). Remove an earlier copy first, or cp nests the new one inside it:
mkdir -p ~/.cursor/plugins/local
rm -rf ~/.cursor/plugins/local/kibi-cursor
cp -R "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursorThe copy needs no node_modules: the hooks run bin/hook-runner.mjs, a
self-contained bundle, and the MCP launcher bin/launch-kibi-mcp.mjs uses
only Node built-ins and starts the opened project's own kibi-mcp. Copy again
after upgrading kibi-cursor.
MCP configuration
The plugin bundles mcp.json with a thin launcher that locates and starts the
kibi-mcp package installed in the opened project. The launcher starts the
resolved child from the consumer workspace and sets KIBI_WORKSPACE to that
root; it never downloads, bundles, or falls back to a global Kibi runtime.
The preToolUse hook adds workspaceRoot (the agent's current workspace) to
every Kibi MCP call, so an agent working in a git worktree is answered from
that worktree's branch. Setting KIBI_WORKSPACE pins one workspace instead:
{
"mcpServers": {
"kibi": {
"command": "node",
"args": [
"${CURSOR_PLUGIN_ROOT}/bin/launch-kibi-mcp.mjs",
"${workspaceFolder}"
]
}
}
}Toggle the bundled MCP server from Settings → Features → Model Context Protocol after installing the plugin.
Cursor expands ${CURSOR_PLUGIN_ROOT} to the installed plugin directory and
${workspaceFolder} to the opened workspace before starting the command.
Unlike the Claude Code, Codex and ZCode launchers, which fall back to a
global kibi-mcp (with a notice on stderr), the Cursor plugin launcher only
runs the opened project's own kibi-mcp: Cursor starts plugin MCP servers
from a host-chosen directory, and a project-local package keeps the server
version tied to the project's kibi-cli and .kb/ schema. Without one it
refuses with an error that says how to install it. To use a global
kibi-mcp anyway, turn off the plugin's MCP server and add the manual entry
below (npx --no-install finds a project-local install first, then a global
one).
Manual MCP fallback (no plugin install required):
{
"mcpServers": {
"kibi": {
"command": "npx",
"args": ["--no-install", "kibi-mcp"]
}
}
}Portable Agent Plugin (Agent Plugins standard)
kibi-cursor also ships a portable Agent Plugins build at agent-plugin/. The Agent Plugins open standard (v1.0.0) packages Agent Skills and MCP servers for any compatible client — Cursor, Copilot, OpenCode, and others — so the same Kibi capabilities load without client-specific adaptation.
agent-plugin/
├── plugin.json # agent-plugins.org/schemas/1.0.0/plugin.schema.json
├── skills/ # canonical Kibi Agent Skills (kibi-usage, kibi-bootstrap, ...)
└── mcp.json # agent-plugins.org/schemas/1.0.0/mcp.schema.json (stdio kibi-mcp)- Cursor loads the portable build directly; Cursor-only components (rules, commands, hooks) remain in the
.cursor-pluginCursor Plugin build. - Both formats are listed in the same marketplace; pick the format your client needs.
- The portable build still requires the project-local
kibi-cli,kibi-mcp, andkibi-corepackages plus SWI-Prolog 9+ (bundled on supported platforms; see Prerequisites above).
Features
Discovery-first rules and skills
- Rules: always-on capability-based workflow guidance plus optional traceability rules for source files.
- Skills:
kibi-usage,kibi-bootstrap,kibi-freshness,kibi-traceability,kibi-decisions,kibi-commit-review, andkibi-provable-code. - Commands:
/kibi-bootstrapdocuments thekb_plan_bootstrapbootstrap workflow, and/kibi-signoffshows the requirements signoff view (or the decisions waiting for you) as Markdown in the chat. The kibi-vscode extension also installs in Cursor and adds the Kibi: Show Requirements Signoff panel.
Advisory editor hooks
Hooks are warning-only and never replace MCP/CLI behavior. hooks/hooks.json runs bin/hook-runner.mjs, a committed self-contained bundle (with kibi-agent-core inlined), so a copied plugin directory or a GitHub marketplace install runs the hooks without node_modules or a build step:
- sessionStart: the shared Kibi session brief (search for recorded intent before changing behaviour, record decisions with their reason, run
kibi check --stagedbefore finishing, ask before making a recorded rule false), with a note when the MCP server or the git hooks are missing. Without.kb/manifest.json, a bootstrap reminder instead. - preToolUse: warns on explicit direct
.kb/**edits without blocking. Before the first edit of a file whose symbols implement a requirement, it adds the shared Kibi snippet (fromkibi-agent-core/snippets, the same builder the Claude Code plugin uses): the requirements and their implementing symbols, what the lead requirement must keep true and the decision behind it, the covering tests, and the symbol the edit lands in. A superseded or retired lead requirement gets no "must keep true" or "Decision" line. Once per path per session. When the edited code implements a firm requirement (a rule the person set), the message first tells the agent to ask the person before an edit that breaks it, once per requirement per conversation (Cursor does not enforce a hook's "ask";KIBI_CONFIRM_FIRM_EDITS=0turns this off). - beforeSubmitPrompt: never blocks a prompt. A prompt that states a rule ("must not", "from now on") leaves a note, delivered with the next pre-edit message, to record that rule with
kb_upsertas part of the change. - beforeReadFile and postToolUse (Read): inject source-linked lookup guidance once per path per session, with the same snippet minus the "must keep true" and "Decision" lines.
- postToolUse (opt-in telemetry): with
KIBI_DIAGNOSTIC_MODE=1, appendsinterface: "hook"rows withhost: "cursor"to.kb/usage.logforkb_*lookups (MCP orkibi <route>in Shell) and for edited files with the requirements they implement, keyed byconversation_id.kibi usage-metricsreads them for thelookup_before_first_editmetric. Nothing is written without the variable. - postToolUse (Write/Edit): inject traceability and freshness guidance once per path per session, including
kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})for meaningful source edits. - stop: emits a single freshness or impact-check follow-up when meaningful paths were edited during the turn (reads and search do not count). Plan delivery (
CreatePlan) stays silent unless that same turn also edited source or mutated the KB. When the conversation changed source files and recorded nothing withkb_upsert, the follow-up also asks, once, for the decision behind the change to be recorded. When the conversation wrote a requirement andkibi signoffhas not run since, it asks, once, for the signoff view to be shown before the work is reported done.
What the plugin does not do
Per the thin-adapter architecture, kibi-cursor does not:
- Own KB storage, parsing, or validation
- Run background
kibi syncor CLIkibi checkfrom hooks (agents select visible MCP tools or trusted project-local CLI JSON routes; for source edits, use impact-enabledkb_checkfirst) - Block agent actions in advisory mode
Architecture
kibi-cursor is a thin bridge layer:
- Agent-visible guidance: visible public MCP tools or trusted project-local CLI JSON routes (
--input), plus a blocked/operator state when neither is available - Editor-specific value: Cursor hooks for read/write reminders and session freshness follow-ups
- Foundation:
kibi-core,kibi-cli, andkibi-mcpremain required for project-local operations
Project-local CLI routes
The trusted project-local CLI JSON routes are an equal peer of the Kibi MCP tools. The always-on kibi-workflow rule uses the MCP tools when they are in the tool list and the project-local CLI otherwise. Hooks stay advisory and never execute that CLI themselves.
For the agent to actually run the CLI routes, the Cursor session needs:
- Agent mode with Shell enabled (Ask mode cannot run the CLI)
- A trusted workspace, or explicit operator approval of the project-local CLI
- Project-local
kibi-cli(usenpx --no-install kibiorbunx --no-install kibi; never a global or installing runner) - Plugin rules loaded in the Cursor harness
If Shell is unavailable or the workspace is untrusted, stop and ask the operator; do not probe the CLI.
A Cursor model invoked outside Cursor's plugin harness will not load this rule. Inject the same always-on guidance into that host's system prompt or AGENTS.md.
License
AGPL-3.0-or-later
