Installation

Prerequisites

Kibi needs Node.js 22+ for the CLI, MCP server, and engine. npm only warns when an older Node is active, so kibi and kibi-mcp check at startup and exit with an error naming the Node they found. Both start through the first node on PATH, so Node.js 22+ must come first there for your shell, your Git hooks, and the agent host that launches kibi-mcp. It also needs SWI-Prolog 9.0+, and on supported platforms that comes with Kibi: you install nothing extra.

Bundled SWI-Prolog

kibi-cli (and kibi-runtime, which kibi-mcp uses) depend on kibi-swipl, which lists one platform package per target as an optional dependency. Your package manager installs only the one that matches your machine:

On these platforms npm install --save-dev kibi-cli kibi-mcp kibi-core followed by kibi init works on a machine with no SWI-Prolog at all. The build is relocatable, ships its own libraries and licenses, and is tested with the same Prolog suites Kibi's own CI runs.

Not covered by a bundled build: Alpine and other musl-based Linux, and native Windows. On Windows, run Kibi inside WSL (a glibc distribution uses the bundled build); otherwise install SWI-Prolog yourself as described below.

Which SWI-Prolog Kibi uses

Kibi picks a SWI-Prolog in this order and uses the first that works:

1. KIBI_SWIPL=<absolute path>: that executable, which must be SWI-Prolog 9.0 or newer. An invalid value is an error, never a silent fallback.
2. The bundled platform package, after Kibi verifies its manifest and the binary's SHA-256.
3. swipl on your PATH, which must be 9.0 or newer.
4. Otherwise Kibi stops with an error that names your platform, the platform package that would have covered it, and the install command for your OS.

When both a bundled build and a system swipl exist, the bundled build wins, so a project behaves the same on every machine that installs the same packages. To use the system install instead, set KIBI_SWIPL=system, which skips the bundle and uses swipl from PATH:

KIBI_SWIPL=system npm exec -- kibi doctor
KIBI_SWIPL=/opt/swipl/bin/swipl npm exec -- kibi doctor

kibi doctor shows what was chosen: the SWI-Prolog check reports the source (bundled, KIBI_SWIPL, or PATH), the executable's path and version, and loads every library Kibi needs, so a SWI-Prolog build that lacks one (for example a minimal swi-prolog-nox package) fails there rather than in the middle of a command. With --format json the same facts appear as details.source, details.path, and details.version.

If the bundled runtime is missing

The platform packages are optional dependencies, so an install can leave them out without failing. kibi doctor and the first command that needs Prolog then name the package to add:

npm install --save-dev kibi-swipl-linux-x64-gnu   # the package for your platform

The usual causes:

• Installing with --omit=optional or --no-optional (or npm_config_omit=optional, optional=false). Install without it.
• pnpm supportedArchitectures (in pnpm-workspace.yaml or package.json) that does not include your platform, for example a Docker build that fixes os/cpu to another machine. Add your platform to it, or build the image for the platform it runs on.
• Installing on one platform and running on another (copying node_modules from macOS into a Linux container, or the reverse). Install on the machine, or in the image, that runs Kibi.
• An Alpine/musl or Windows host, which has no bundled build; see below.

Installing SWI-Prolog yourself

Do this on platforms with no bundled build, or when you want Kibi to use a system install through KIBI_SWIPL=system or KIBI_SWIPL=<path>. Kibi needs SWI-Prolog 9.0 or newer with its standard libraries (semweb, pcre, crypto, http/json, chr, and others, all in a normal full install).

Ubuntu (Recommended)

The official SWI-Prolog project provides a Personal Package Archive (PPA) for Ubuntu that stays current with every release.

sudo apt-get install software-properties-common
sudo apt-add-repository ppa:swi-prolog/stable
sudo apt-get update
sudo apt-get install swi-prolog

Other Linux Distributions

Official Linux distribution packages are often outdated. For other Linux distributions, including Alpine, please refer to the official SWI-Prolog documentation:

• Unix/Linux installation guide - Comprehensive instructions for building from source or using other methods
• Stable downloads page - Source archives and binaries
• Flatpak - Available for most Linux distributions

macOS

brew install swi-prolog

Windows

Use the installer from the stable downloads page and let it add swipl to your PATH, or set KIBI_SWIPL to the full path of swipl.exe. Alternatively run Kibi inside WSL, which uses the bundled build and needs no SWI-Prolog install.

Verify a system install

swipl --version

You should see output like SWI-Prolog version 10.x.x.

Installing kibi

Recommended: Agent-led setup

Kibi is operated by your coding agent, so the recommended install is a prompt. Paste this into Claude Code, Cursor, Codex, OpenCode, or any coding agent that can run commands in your repository:

Set up Kibi (https://github.com/Looted/kibi) in this repository, then bootstrap its knowledge base.

1. Install: confirm Node.js 22+ is available. With the package manager this repository already uses, add kibi-core, kibi-cli and kibi-mcp as dev dependencies. Do not skip optional dependencies; the bundled SWI-Prolog runtime is one.
2. Initialize: run every `kibi` command through the package manager's local runner (npm: `npm exec -- kibi <command>`). Run `kibi init`; if it reports a problem, run `kibi doctor` and fix what it names. If this platform has no bundled SWI-Prolog, tell me what to install and stop.
3. Connect: register the project-local `kibi-mcp` server for the agent host you are running in, following https://looted.github.io/kibi/guide/connect-an-agent.html. Prefer project-scoped configuration, and ask me before installing a plugin or changing global settings. Until the kb_* tools are visible to you, use Kibi's CLI JSON routes instead.
4. Bootstrap: run `kibi skills load kibi-bootstrap --format markdown` and follow that skill exactly. It starts by asking me where product intent lives outside the code (issue trackers, wikis, specs) and which sources to trust; read them through the connectors you have and cite them. Show me the complete plan and its hash, and write nothing until I approve it.
5. Verify: run `kibi check` and `kibi status`, fix anything they report, and summarize what was added. Do not commit; I will review the changes.

The agent picks your package manager, installs the three packages project-locally, runs kibi init, registers the kibi-mcp server for its own host, and runs the bootstrap workflow. It writes no product knowledge until you approve the plan, and it leaves the changes uncommitted for your review. The rest of this section is the manual route, and the reference for what the agent does.

npm install --save-dev kibi-cli kibi-mcp kibi-core

pnpm add -D kibi-cli kibi-mcp kibi-core
yarn add -D kibi-cli kibi-mcp kibi-core
bun add -d kibi-cli kibi-mcp kibi-core

minimumReleaseAgeExclude:
  - "kibi-*"

npm exec -- kibi --version
npx --no-install kibi-mcp --help

The CLI and MCP server are peer agent-operation surfaces. MCP-capable hosts can call the public kb_* contracts directly; agents in trusted project-local shells can invoke the equivalent CLI JSON routes with kibi <route> --input <file|->. Neither path requires direct access to .kb/** files.

Kibi release versions

Each Kibi package keeps its own semantic version, so kibi-cli 2.41.0, kibi-mcp 3.25.0 and kibi-core 0.30.0 can belong to the same release. Every release therefore also gets one Kibi release version in calendar form, YYYY.M.N: 2026.11.0 is the first release in November 2026, and 2026.11.1 is the next one. A release version names an exact package set and says nothing about compatibility on its own.

• kibi --version prints both versions, for example Kibi 2026.11.0 (kibi-cli 2.41.0).
• kibi doctor reports the release under "Kibi release". If an installed Kibi package has a version other than the one that release lists, it warns with a "Mixed install" message that names each package. The JSON output (kibi doctor --format json) carries the full manifest under runtime.release.
• The MCP server's title names the release, for example Kibi MCP (Kibi 2026.11.0).
• Each release is published as a kibi@<release> GitHub release that lists every package version, with the manifest attached as release.json. To install a specific release, install the versions it lists.

The manifest ships in kibi-core as release.json. It also declares the compatibility versions of that release:

Compatibility questions key off these numbers, not off package versions. A KB at schemaVersion 13 works with every release whose kbSchema.current is 13, whatever its package versions are.

Update notices

When a newer kibi-cli is published on npm, the CLI prints one line on stderr after a command, for example:

Kibi update available: kibi-cli 2.41.0 -> 2.42.0. Update with 'npm install -D kibi-cli@latest'. (KIBI_UPDATE_CHECK=0 turns this off)

The update command matches the install: the project's package manager (from its lockfile) for a project dependency, npx kibi-cli@latest for an npx cache, and a global install otherwise. When the newer release writes a newer KB schema (kibi.kbSchema in its package.json), the line also names the schema move and asks you to run kibi migrate after updating. Update kibi-mcp and the other Kibi packages to the same release; kibi doctor warns about a mixed install.

• The CLI asks the npm registry for the latest kibi-cli at most once a day, from a detached background process, so no command waits on the network. The request sends nothing about you or the project, and the answer is cached in Kibi's per-user state directory (update-check.json next to the telemetry settings). It uses KIBI_UPDATE_REGISTRY, then npm_config_registry, then https://registry.npmjs.org.
• The line appears at most once a day per version, and only when stderr is a terminal. Agent and hook runs, pipes, commands that print JSON (--json, --format json, --input), CI and test runs, local dev builds and a Kibi source checkout never show it and never check.
• KIBI_UPDATE_CHECK=0 or NO_UPDATE_NOTIFIER=1 turns the check off entirely.
• kibi doctor reports the same answer under "Kibi updates" for every agent host and for the plain CLI: a newer version is a warning with the update command, an unreachable registry is neither a warning nor a failure.

First-run lifecycle

After installing the packages, use this short path:

1. Run kibi init to create repository infrastructure and Git hooks.
2. Ask your coding agent to “Bootstrap Kibi for this repository.” The agent first asks where product intent lives outside the code (issue trackers, wikis, specs) and which of those sources are authoritative, reads them through its own connectors, and passes cited intent claims to the read-only kb_plan_bootstrap planner. After that it asks only questions returned by a needs_context result, and shows the exact plan for approval.
3. After approval, the agent passes the unchanged returned plan to kb_apply_plan, then runs kb_check and kb_status.
4. Continue normal work with the seeded Kibi context. Use kibi doctor only when typed status says infrastructure is degraded.

Fresh clones and new machines

kibi init runs once per repository, but .git/hooks, the compiled branch store and agent plugins never travel with a clone. So that a teammate's or an agent's fresh clone still uses Kibi, kibi init also:

• writes a Kibi section into AGENTS.md and an @AGENTS.md import into CLAUDE.md, so every coding agent, with or without a Kibi plugin, is told the knowledge base exists and how to query it;
• adds kibi hooks install --quiet to the root package.json prepare script, so installing dependencies installs the hooks (without a root package.json, run kibi hooks install after cloning);
• records these choices in package.json kibi.setup (or .kb/setup.json).

The first Kibi query, check or write in a clone compiles the branch store from the committed sources, and agent plugins tell the agent at session start when the hooks are missing. Each piece can be turned off; see setup choices. An optional pull-request gate (kibi init --ci-gate) runs kibi check in CI, where no local hook can.

Existing Git hooks and hook managers

Git runs one script per hook, so Kibi and another tool cannot both own .git/hooks. kibi init never edits a hook it did not write (the section between # BEGIN kibi-managed and # END kibi-managed is the only part it touches); it reports such a hook as skipped instead. When the repository uses a hook manager, Kibi leaves the hooks to the manager and you add Kibi's commands to the manager's configuration.

These are the commands Kibi's own hooks run. Any setup that runs the same commands under the same conditions is equivalent:

The sync hooks compile the checked-out branch's KB store, so tools and the next commit see current knowledge; the pre-commit commands are Kibi's commit gate. Hooks never run in CI: run kibi sync there (with KIBI_BRANCH set when the checkout is a detached HEAD) before kibi check.

What kibi init does. It detects lefthook (a lefthook.yml or its variants, or hook runners lefthook generated), husky (core.hooksPath set to .husky or .husky/_, or a .husky/ directory) and the pre-commit framework (.pre-commit-config.yaml or hooks it generated). With one present it installs nothing into the hooks directory and prints the configuration to add for every hook the manager does not visibly run Kibi's commands for yet. Use --no-hooks to skip hook setup altogether.

Print the configuration in your manager's format at any time; it writes nothing:

npx --no-install kibi init --print-hook all --format lefthook    # or husky, pre-commit
npx --no-install kibi init --print-hook pre-commit               # one hook, as a shell snippet

--print-hook takes pre-commit, post-checkout, post-merge, post-rewrite or all; --format takes shell (the default), lefthook, husky or pre-commit.

• lefthook: merge the printed entries into lefthook.yml, then run lefthook install:

  yamlCopy

  pre-commit:
    commands:
      kibi-check:
        run: npx --no-install kibi check-generated --staged --changed-only && npx --no-install kibi check --staged
  post-checkout:
    commands:
      # {3} is 1 for a branch checkout, 0 for a file checkout.
      kibi-sync:
        run: if [ "{3}" = "1" ]; then npx --no-install kibi sync; fi
  post-merge:
    commands:
      kibi-sync:
        run: npx --no-install kibi sync
  post-rewrite:
    commands:
      kibi-sync:
        run: if [ "{1}" = "rebase" ]; then npx --no-install kibi sync; fi

• husky (or any hand-written shell hook): append the printed snippet to each hook file. It finds a project-local kibi even when node_modules/.bin is not on the hook's PATH, and stops the commit if either check fails:

  bashCopy

  npx --no-install kibi init --print-hook pre-commit >> .husky/pre-commit
  npx --no-install kibi init --print-hook post-checkout >> .husky/post-checkout
  npx --no-install kibi init --print-hook post-merge >> .husky/post-merge
  npx --no-install kibi init --print-hook post-rewrite >> .husky/post-rewrite

• pre-commit framework: merge the printed local hooks into .pre-commit-config.yaml and add the hook types to default_install_hook_types, then run pre-commit install. The post-checkout and post-rewrite entries read the hook arguments from PRE_COMMIT_CHECKOUT_TYPE and PRE_COMMIT_REWRITE_COMMAND.

Calling the commands through a task runner (task, make, just, an npm script) works too. kibi doctor reads the manager's configuration (lefthook YAML or JSON, .husky/<hook>, .pre-commit-config.yaml) and passes each hook that visibly runs Kibi's commands. It cannot follow a task runner, so a hook that reaches Kibi that way is reported as a warning naming the commands to check, never as a failure.

Avoid auto-install or hot-load commands for MCP startup (npx -y, pnpm dlx / pnx, or yarn dlx) unless you intentionally want the client to fetch a package outside the project lockfile.

OpenCode MCP

For OpenCode, add a local MCP server in opencode.json. OpenCode uses a token-array command field. This npm example is local-only and does not download packages at startup:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kibi": {
      "type": "local",
      "command": ["npx", "--no-install", "kibi-mcp"],
      "enabled": true
    }
  }
}

If your project uses another package manager, keep the same MCP shape and use that manager's local binary runner. For example, pnpm projects can use:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kibi": {
      "type": "local",
      "command": ["pnpm", "exec", "kibi-mcp"],
      "enabled": true
    }
  }
}

VS Code MCP

For VS Code, create .vscode/mcp.json. VS Code uses a command string with a separate args array:

{
  "servers": {
    "kibi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--no-install", "kibi-mcp"]
    }
  }
}

If you use pnpm, replace "command": "npx" and "args" with:

{
  "servers": {
    "kibi": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["exec", "kibi-mcp"]
    }
  }
}

Optional: OpenCode plugin

kibi-opencode is an optional OpenCode plugin. It injects Kibi guidance, provides the /kibi-bootstrap convenience command when the host supports it, and runs background sync/check maintenance. When the file being edited implements a requirement, the guidance names it, what it must keep true, and the decision behind it. Canonical bootstrap behavior lives in the bundled kibi-bootstrap skill (kb_plan_bootstrap, preview, apply via the approved plan). Generic MCP agents should start from generic-agent onboarding. The plugin does not ship a replacement kibi or kibi-mcp binary, so keep the base kibi-cli, kibi-mcp, and kibi-core packages installed and keep the mcp.kibi server configured separately.

npm install --save-dev kibi-opencode

{
  "plugin": ["kibi-opencode"]
}

The OpenCode plugin auto-updates itself by default on OpenCode startup. This only refreshes OpenCode's cached kibi-opencode package; it does not update your project-local kibi-cli, kibi-mcp, or kibi-core dependencies. To lock the plugin, use an exact semver entry in the plugin array:

{
  "plugin": ["kibi-opencode@<version>"]
}

Set autoUpdate: false in .opencode/kibi.json or ~/.config/opencode/kibi.json to disable the startup updater entirely.

A plugin array entry always installs from npm into OpenCode's cache, never from the project's node_modules, and a file:// path there does not load. To run the version installed in the project instead, drop the array entry and re-export it from .opencode/plugins/kibi.js:

export { default } from "../../node_modules/kibi-opencode/dist/index.js";

The local file is not auto-updated; it follows the project's installed version. See packages/opencode/README.md.

The plugin's internal maintenance expects a kibi CLI command to be available from the project context or PATH; the canonical setup above satisfies that by installing kibi-cli project-locally.

OpenCode v1 and v2

The same kibi-opencode package loads on OpenCode v1 (1.4 and later) and on OpenCode v2. The default export carries both plugin shapes: v1 reads { id, server } (and { id, tui } for the TUI entry), and v2 reads { id, setup }. Install and configure it the same way on either version.

A directory install (a distro package or a local folder) does not read package.json "exports". The package ships root index.js and tui.js shims that re-export the built server and TUI entries, so both parts load. Without tui.js, that install reports the server plugin only.

On OpenCode v2:

• Kibi guidance, background sync/check maintenance, and /kibi-bootstrap work as on v1. Syncs triggered by file changes come from completed edit, write, and patch tool calls. On OpenCode v2.0.32 a plugin can async-iterate event.subscribe() and will see public bus events, including filesystem.changed, but the host publishes that event only for the VCS HEAD file (creating a branch delivered { type: "filesystem.changed", data: { file: "<repo>/.git/HEAD", event: "change" } }). A bash rm or mv, appending to a tracked file, and git checkout -- <file> produced no file.created, file.edited, file.deleted, or filesystem.changed event. The SDK's file.watcher.updated type is not in the v2.0.32 binary, and file.edited is only a schema with no publish site. Changes from bash, git checkout, or an external editor therefore do not trigger a Kibi sync. Run kibi sync yourself, or rely on the post-checkout, post-merge, and post-rewrite hooks installed by kibi init (each runs kibi sync). The next status refresh also picks up the working tree. kibi sync reads only documents Git tracks (staged is enough), so a new document written outside the agent needs git add before kibi sync imports it. Documents written through kb_upsert are covered until then.

• v2 has no toast or structured plugin log, so kibi-opencode shows no toasts and reports plugin errors on stderr with a [kibi-opencode] prefix.

• Code Mode: v2 exposes MCP tools through Code Mode by default. On OpenCode v2.0.32 the catalog lists kibi (16 tools, 1 shown), search({ query: "kibi" }) finds all 16, and the tools are reachable through execute under tools.kibi. To call the native kibi_* tools directly, set codemode: false on a v2-native server entry under mcp.servers:

  jsonCopy

  {
    "mcp": {
      "servers": {
        "kibi": {
          "type": "local",
          "command": ["npx", "kibi-mcp"],
          "codemode": false
        }
      }
    }
  }

  Setting codemode on a v1-style entry (mcp.kibi with enabled) has no effect: OpenCode v2 migrates v1 entries and drops that key. OpenCode v1 reads every key under mcp as a server name, so keep this entry in a configuration that only OpenCode v2 reads.

• OpenCode v1 and v2 share the same opencode.db. To run both on one machine, give each its own XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME, and XDG_CONFIG_HOME.

Optional: Codex plugin

kibi-codex is an optional adapter that gives Codex users prepackaged Kibi skills, hooks, and MCP configuration. It builds on kibi-core, kibi-cli, and kibi-mcp and does not replace them.

Install through the repo-scoped Kibi marketplace:

codex plugin marketplace add Looted/kibi
codex

Then run /plugins, choose Kibi Plugins, and install kibi-codex.

The marketplace lives at .agents/plugins/marketplace.json and points Codex at ./packages/codex, where the plugin manifest, skills, hooks, and MCP config are stored. Codex resolves that path relative to the marketplace root. Local marketplace installs copy the plugin directory as-is. The committed bin/hook-runner.mjs makes lifecycle hooks work from an unbuilt source checkout; run bun run build:codex when you also need refreshed generated skills or MCP configuration. (Packed npm installs run the build automatically via prepack.)

Workspace opt-in rule

The plugin may be installed and enabled globally, but it only activates in workspaces that opted into Kibi:

• A workspace is opted in when its Kibi project root owns .kb/manifest.json (the manifest kibi init creates). Installing the plugin, having kibi-mcp on PATH, or enabling the plugin in ~/.codex/config.toml never counts.
• Project-root resolution honors the standard KIBI_WORKSPACE, KIBI_PROJECT_ROOT, and KIBI_ROOT environment overrides, then walks up from the session directory and stops at the first .kb/manifest.json (opted in) or .git boundary (not opted in). Subdirectories of an opted-in repository map to that repository; a Git worktree is evaluated by its own root and never inherits the main checkout's state; an unrelated enclosing repository never leaks opt-in into a nested project.
• In unconfigured workspaces every hook exits successfully and silently — no bootstrap prompts, no edit tracking, no reminders, no state writes — and the MCP server starts with an empty tool catalog. Nothing is initialized or written unless you explicitly ask for it (kibi init or the kibi-bootstrap skill).
• In opted-in workspaces the plugin behaves as before: hooks warn about direct .kb edits, track changed paths, and surface freshness/impact reminders at session stop, scoped to the workspace they were generated in, so activity in one project cannot generate reminders in another.
• Before apply_patch (or another edit tool) changes a file whose symbols are linked to a requirement, PreToolUse adds a short snippet to the agent's context: the requirement, what it must keep true (its linked facts), the decision behind it (its ADR), and the tests that cover it. It covers up to three changed files per call, once per file per session, and a superseded or retired requirement is never presented as current.

Codex host limitations and the MCP launcher

Codex (verified against codex-cli 0.153.4) has no workspace-scoped or content-conditional activation for plugins or their MCP servers: plugin enablement is global, and legacy .codex-plugin MCP entries support no placeholder expansion or plugin-root environment. To keep non-Kibi workspaces free of MCP startup errors, the plugin's .mcp.json therefore inlines a launcher (node -e, built from packages/codex/bin/mcp-launcher.cjs) that:

• resolves the workspace from the active session cwd and the opt-in rule above;
• serves a silent MCP server with zero tools in unconfigured workspaces;
• probes and proxies the project-local kibi-mcp (npx --no-install kibi-mcp, exactly the previous config) in opted-in workspaces, with KIBI_WORKSPACE set to the resolved root;
• starts cleanly with a guidance message when an opted-in workspace has no resolvable kibi-mcp executable — the MCP handshake still succeeds, so no startup error is reported.

The launcher is a supported stdio server from Codex's point of view; it simply stays empty unless the workspace opted in.

For local development or npm package smoke testing, you can also install the adapter package with your project-local dependencies:

npm install --save-dev kibi-codex

The official OpenAI Plugin Directory does not currently provide self-serve public plugin publishing. Use the repo marketplace or a local plugin fixture while developing/testing.

The installed plugin package contributes:

• .codex-plugin/plugin.json manifest
• .mcp.json MCP config with the inline workspace-opt-in launcher
• hooks/hooks.json lifecycle hooks
• skills/*/SKILL.md Kibi workflow guidance

Review hook trust policy before enabling automatic trust:

• confirm the plugin source and hook paths are expected in your environment
• review local trust settings if your Codex host requires explicit plugin trust
• prefer warning-only behavior and disable automatic trust for unvetted sources

Manual MCP fallback (no plugin install required): keep base dependencies and configure your Codex MCP client directly:

[mcp_servers.kibi]
command = "npx"
args = ["--no-install", "kibi-mcp"]

This fallback is supported for teams that do not use the adapter package.

Optional: Cursor plugin

kibi-cursor is an optional adapter that gives Cursor users prepackaged Kibi rules, skills, commands, MCP configuration, and advisory editor hooks. It builds on kibi-core, kibi-cli, and kibi-mcp and does not replace them.

Install from the repo marketplace at .cursor-plugin/marketplace.json, which points at ./plugins/kibi-cursor. For local development, copy the built plugin into Cursor's user-plugins directory (symlinks are rejected on WSL):

./scripts/sync-cursor-plugin-local.sh

On WSL workspaces, Cursor reads ~/.cursor/plugins/local in your Linux home. Restart Cursor or run Developer: Reload Window, then check Plugins → User.

You can also install the npm package for smoke testing:

npm install --save-dev kibi-cursor

The installed plugin package contributes:

• .cursor-plugin/plugin.json manifest
• mcp.json MCP config with a launcher that resolves and starts the kibi-mcp installed in the opened project
• hooks/hooks.json advisory lifecycle hooks; before Cursor reads or edits a file whose symbols implement a requirement, they show that requirement and its tests, and before an edit, what it must keep true and the decision behind it
• rules/*.mdc workflow and traceability guidance
• skills/*/SKILL.md Kibi workflow skills
• commands/kibi-bootstrap.md bootstrap command guidance

The plugin launcher runs the consumer project's kibi-mcp with the opened workspace as its current directory and with KIBI_WORKSPACE set to that root. It does not download, bundle, or use a global Kibi runtime. Install the base packages in each project before enabling the plugin MCP server.

Manual MCP fallback (no plugin install required):

{
  "mcpServers": {
    "kibi": {
      "command": "npx",
      "args": ["--no-install", "kibi-mcp"]
    }
  }
}

See Cursor Plugins and packages/cursor/README.md for hook behavior and local testing details.

Optional: ZCode plugin

kibi-zcode is an optional adapter that gives ZCode users prepackaged Kibi skills, a /kibi-bootstrap command, advisory lifecycle hooks, and MCP configuration. It builds on kibi-core, kibi-cli, and kibi-mcp and does not replace them.

Local ZCode development, package builds, and tests currently use Linux/WSL. The launcher retains shell-free runtime handling for Windows npm shims.

Install through the repo marketplace from a locally built checkout:

1. Clone this repository and run bun run build:zcode in it. A marketplace install from a local directory copies the plugin directory as-is, and an install from a tree without a build is missing dist/hook-runner.js, so every lifecycle hook fails to start.
2. In ZCode, open Settings → Plugin Management → Discover, use the + button, choose local directory, and select the repository root — the directory that contains .claude-plugin/marketplace.json (the manifest points ZCode at ./packages/zcode).
3. Install kibi-zcode from the Kibi marketplace. New installs are enabled by default.

GitHub-source installs are not supported. Adding Looted/kibi as a GitHub marketplace cannot work today: the plugin's dist/hook-runner.js is generated by the build and is not committed, so a GitHub-sourced copy has no hook runner. This route stays unsupported until a built remote distribution exists. Note that prepack (the automatic build for packed npm installs) runs only for npm pack/npm install kibi-zcode packaging flows — ZCode's marketplace copy never builds anything.

The installed plugin package contributes:

• .zcode-plugin/plugin.json manifest with the inline mcpServers entry
• bin/mcp-launcher.cjs workspace-gated MCP launcher (resolves kibi-mcp shell-free: the project-local package entry through Node's own resolution, then a PATH lookup, with the Windows npm-shim layout handled without a command interpreter)
• hooks/hooks.json advisory lifecycle hooks (SessionStart, PreToolUse, PostToolUse, Stop)
• skills/*/SKILL.md Kibi workflow skills (frontmatter rewritten for ZCode's skill loader; bodies and resources are byte-identical to the canonical bundled skills)
• commands/kibi-bootstrap.md slash command that routes into the kibi-bootstrap skill

The plugin follows the same workspace opt-in rule as the Codex adapter: hooks and the MCP launcher stay completely silent in workspaces whose Kibi project root does not own .kb/manifest.json. In opted-in workspaces, the MCP launcher proxies the resolved kibi-mcp with KIBI_WORKSPACE set, and hooks are advisory only — they warn about direct .kb edits, track file mutations per host session (read-only tool calls never count as changes, and a later edit invalidates an earlier impact check for that path), and surface freshness/impact reminders at session stop with workspace-relative paths. Before an edit of a file linked to a requirement, PreToolUse adds the requirement, what it must keep true, the decision behind it, and its tests to the agent's context, once per file per session. The hard enforcement gate remains the kibi check --staged git hook installed by kibi init.

Manual MCP fallback (no plugin install required):

{
  "mcpServers": {
    "kibi": {
      "command": "npx",
      "args": ["--no-install", "kibi-mcp"]
    }
  }
}

See packages/zcode/README.md for the ZCode declaration contract the plugin targets (hook events, output schema, skill frontmatter rules).

Optional: Claude Code plugin

kibi-claude is an optional Claude Code adapter. It builds on kibi-core, kibi-cli, and kibi-mcp and does not replace them. It contributes:

• the workspace-gated Kibi MCP server;
• the seven bundled Kibi skills, invoked as /kibi-claude:kibi-usage, /kibi-claude:kibi-bootstrap, and so on;
• advisory hooks that show the agent requirement and test context before it reads or edits linked code (before an edit, also what the requirement must keep true and the decision behind it), and remind it once to run an impact check before finishing.

The repository root is a Claude Code marketplace, and the hook runner is a committed self-contained bundle, so a GitHub install needs no build:

claude plugin marketplace add Looted/kibi

claude plugin install kibi-claude@kibi

To try a local checkout without installing, run claude --plugin-dir packages/claude from a Kibi workspace.

The plugin follows the same workspace opt-in rule as the Codex and ZCode adapters: hooks and the MCP launcher stay completely silent in workspaces whose project root does not own .kb/manifest.json. Hooks read a cached index of .kb/symbols.yaml instead of calling the CLI, so they add tens of milliseconds per tool call. The hard enforcement gate remains the kibi check --staged git hook installed by kibi init. See packages/claude/README.md for exactly what each hook emits and how often.

Cloud sessions (Claude Code on the web and in the desktop app) load the plugin only when the repository enables it: commit extraKnownMarketplaces for Looted/kibi and "enabledPlugins": {"kibi-claude@kibi": true} to the repository's .claude/settings.json (the exact snippet is in packages/claude/README.md).

Optional: languages beyond TypeScript and JavaScript

TypeScript and JavaScript symbols are built in. For Python, Go, Rust, Java, C#, PHP, C, C++, Bash, Ruby, SWI-Prolog and Terraform/HCL, add the optional kibi-plugin-treesitter package and the grammar pack of each language the repository uses. Each pack is a small data-only kibi-lang-* package: kibi-lang-python, kibi-lang-go, kibi-lang-rust, kibi-lang-java, kibi-lang-csharp, kibi-lang-php, kibi-lang-c, kibi-lang-cpp, kibi-lang-bash, kibi-lang-ruby, kibi-lang-hcl and kibi-lang-prolog. kibi init and kibi doctor name the packs the tracked sources need, at the version the plugin pins. Generated files (linguist-generated in .gitattributes, or a generator header) count only when the KB references them, and a pack the project does not want can go in package.json kibi.declinedLanguagePacks; see the plugin guide.

npm install --save-dev kibi-plugin-treesitter kibi-lang-python kibi-lang-go

Then activate it in package.json. kibi.symbol-extractor.v2 gives symbols, their coordinates and the commit gate for those languages; kibi.reference-extractor.v1 also lets source proofs read what Go, Java, C#, Rust, PHP, C and Bash files import, call and read from the environment, and the values Terraform/HCL files set:

{
  "kibi": {
    "plugins": [
      {
        "package": "kibi-plugin-treesitter",
        "capabilities": {
          "kibi.symbol-extractor.v2": { "mode": "augment" },
          "kibi.reference-extractor.v1": { "mode": "augment" }
        }
      }
    ]
  }
}

A project without a package.json (a Go, Rust or Java project, say) creates a minimal one first with npm init -y; Kibi reads only its devDependencies and kibi.plugins. Add node_modules/ to .gitignore. Code and source proofs read TypeScript, JavaScript, Python and SWI-Prolog without the plugin. The plugin reference and the kibi-plugin-treesitter README cover symbol titles, partial analysis and what each language reads; proving requirements covers what source proofs list and refuse in each language.

Optional capability plugins

Builtin classification, ontology matching, and symbol extraction need no plugin configuration. Installing an optional package does not activate it.

install package → explicitly activate in package.json → provide required secret/environment → restart long-lived Kibi MCP/client runtime

kibi-plugin-jev is the optional TypeSafe semantic classifier. It is not part of the default Kibi install.

npm install --save-dev kibi-plugin-jev

{
  "kibi": {
    "plugins": [
      {
        "package": "kibi-plugin-jev",
        "capabilities": {
          "kibi.semantic-classifier.v1": {
            "mode": "augment"
          }
        }
      }
    ]
  }
}

Set provider secrets through Kibi-owned env files (same resolution for every harness that starts kibi / kibi-mcp — no Cursor/OpenCode/Codex/ZCode-specific secret config is required):

mkdir -p ~/.config/kibi
printf '%s\n' 'TYPESAFE_API_KEY=...' >> ~/.config/kibi/env

Optional project override: <workspace>/.env.kibi. Existing process environment variables always win. KIBI_ENV_FILE replaces the project file path. A legacy <workspace>/.env is still loaded for compatibility to fill remaining gaps, but is not preferred (it can pull unrelated app secrets into Kibi). Restart long-running MCP or host processes after changing env files. Do not put secrets in package.json.

Optional settings:

Modes:

augment — builtin handles normal cases; external provider helps unresolved/ambiguous cases
replace — configured provider owns the capability; builtin is only failure fallback
shadow — provider runs for comparison but cannot affect canonical output

Removing the kibi.plugins entry disables the plugin. Restart long-running MCP or host processes after plugin configuration changes. Activating a third-party package grants that package code-execution trust. permissions metadata is disclosure, not sandbox enforcement.

kibi doctor lists configured packages, capabilities, modes, and dependency declaration without importing plugin packages. For first-party Jev it also reports secret source labels (process / project_env / user_env / legacy_env / missing) without values, plus effective model and timeout from env. It fails when a known first-party plugin secret is missing. Legacy .env sources get a migration hint. Deeper authoring rules live in plugin-development.md.

Optional: Global install

Global install is convenient for interactive use across projects, but local install is preferred for reproducibility.

npm install -g kibi-cli kibi-mcp kibi-core

Optional Bun alternative:

bun add -g kibi-cli kibi-mcp kibi-core

If kibi is not found afterwards, add the directory printed by npm config get prefix (plus /bin on macOS and Linux) to your PATH.

Local checkout workflow

When a workspace is intentionally configured to run Kibi from a local checkout, invoke that checkout's wrapper or binary directly. Do not use pnpm exec kibi-mcp in an application repository unless you intend to run that repository's installed node_modules version. After changing package versions or local package wiring in a checkout used by another workspace, rebuild before testing or using OpenCode with those local artifacts:

bun run build

Troubleshooting Installation

SWI-Prolog Issues

Start with npm exec -- kibi doctor: it reports which SWI-Prolog Kibi chose, from where, and whether every required library loads.

• could not find a usable SWI-Prolog: the message names your platform and the platform package that should have supplied it. Add that package (see If the bundled runtime is missing), or install SWI-Prolog 9.0+ and put swipl on PATH, or set KIBI_SWIPL.
• The bundled SWI-Prolog package ... is damaged: reinstall the platform package, or set KIBI_SWIPL=system to use swipl from PATH meanwhile.
• KIBI_SWIPL=... is not an executable file (or is too old): KIBI_SWIPL must be the absolute path of a SWI-Prolog 9.0+ executable, or system. Unset it to use the bundled build.
• A system SWI-Prolog is installed but ignored: that is the default when the bundled package is present. Set KIBI_SWIPL=system to prefer swipl from PATH.

If you need help with SWI-Prolog itself:

• Refer to the SWI-Prolog build documentation for platform-specific guidance
• Check the SWI-Prolog FAQ
• Report issues on the SWI-Prolog forum

Next Steps

1. Paste the agent setup prompt into your coding agent. It covers steps 2 to 4.
2. Check the environment: npm exec -- kibi doctor
3. Initialize the repository: npm exec -- kibi init
4. Connect your coding agent and ask it to "Bootstrap Kibi for this repository."
5. Open the health report: npm exec -- kibi report --open

The CLI reference documents every command, and Troubleshooting covers recovery.