Skip to content

install.md

Latest commit

 

History

History
260 lines (194 loc) · 7.44 KB

install.md

File metadata and controls

260 lines (194 loc) · 7.44 KB

Installation Guide

This document provides detailed installation instructions for kibi.

Prerequisites

Kibi depends on SWI-Prolog 9.0+. You must have swipl installed and available in your PATH before installing kibi.

Installing SWI-Prolog on Linux

Ubuntu (Recommended)

The official SWI-Prolog project provides a Personal Package Archive (PPA) for Ubuntu that stays current with every release. This is the recommended installation method for Ubuntu users.

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, please refer to the official SWI-Prolog documentation:

Verify SWI-Prolog Installation

After installation, verify that swipl is available:

swipl --version

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

Installing kibi

Recommended: Project-local install

For a reproducible, CI-friendly workflow, install kibi as project-level dev dependencies. Use your project's package manager; npm is shown as the Node baseline:

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

Equivalent project-local installs:

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

kibi-mcp depends on compatible kibi-cli and kibi-core versions, but installing all three explicitly makes version pinning and lockfile review clear.

After installation, verify the tools from the local project using your package manager's local binary runner:

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

For other package managers, use the same local-runner pattern:

Package manager CLI example MCP example
npm npm exec -- kibi status npx --no-install kibi-mcp --diagnostic-mode
pnpm pnpm exec kibi status pnpm exec kibi-mcp --diagnostic-mode
Yarn yarn exec kibi status yarn exec kibi-mcp --diagnostic-mode
Bun bunx --no-install kibi status bunx --no-install kibi-mcp --diagnostic-mode

Common environment check: npm exec -- kibi doctor.

Validation command: npm exec -- kibi check.

Avoid auto-install or hot-load commands for MCP startup (npx -y, pnpm dlx / pnx, yarn dlx, or bunx without --no-install) 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", "--diagnostic-mode"],
      "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", "--diagnostic-mode"],
      "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", "--diagnostic-mode"]
    }
  }
}

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

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

Optional: OpenCode plugin

kibi-opencode is an optional OpenCode plugin. It injects Kibi guidance, provides the /init-kibi convenience command when the host supports it, and runs background sync/check maintenance. It 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 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.

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

Command Not Found

If you see "command not found" after installing kibi globally, you may need to adjust your PATH:

  1. Check global npm/bin location:

    npm config get prefix

    The output shows where npm installs global packages.

  2. Add to PATH (if needed): Add the global bin directory to your shell configuration:

    # For bash (in ~/.bashrc or ~/.bash_profile):
export PATH="$PATH:/usr/local/bin"
# For zsh (in ~/.zshrc):
export PATH="$PATH:/home/$USER/.npm-global/bin"

  3. Reload your shell configuration:

    source ~/.bashrc  # or source ~/.zshrc

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

If you encounter problems with SWI-Prolog:

Next Steps

After installing kibi and verifying SWI-Prolog:

  1. Verify your environment: npm exec -- kibi doctor
  2. Initialize your project: npm exec -- kibi init (installs hooks by default and adds .kb/ to .gitignore)
  3. Import documentation: npm exec -- kibi sync
  4. Explore the KB: npm exec -- kibi search <query>
  5. Inspect branch freshness: npm exec -- kibi status
  6. Validate integrity: npm exec -- kibi check

See Entity Schema for details on entity types and when to use each. Example:

npm exec -- kibi doctor
npm exec -- kibi init
npm exec -- kibi sync
npm exec -- kibi search auth
npm exec -- kibi status
npm exec -- kibi check

For more details, see: