@llmkb/claude-code

llmkb (LLM Knowledge Base) is a SaaS AI knowledge platform that transforms raw documents into an organized, interlinked knowledge graph. This plugin connects Claude Code to your llmkb spaces — search, read, and write your knowledge base directly from your editor.

Prerequisites: Node.js >= 20, a running llmkb server (local Docker stack or remote deployment).

Quick Start

# 1. Install the CLI
npm install -g @llmkb/claude-code

# 2. Scaffold config in your project
cd my-project
llmkb init

# 3. Authenticate with your access token
llmkb login --project-space <space-uuid>

# 4. Verify everything works
llmkb doctor

# 5. Sync local files to your llmkb space (optional)
llmkb sync

Commands

llmkb init — Scaffold configuration

Sets up .claude-plugin/, .mcp.json, .llmkb/spaces.yml, and skills in your project. Run this first.

llmkb init                                    # Interactive setup — prompts for space config
llmkb init --platform cursor                  # Generate Cursor rules instead of Claude Code config
llmkb init --platform claude                  # Generate Claude Code config (default)
llmkb init --with-skills                      # Install Claude Code skills
llmkb init --without-skills                   # Skip skill installation
llmkb init --with-hooks                       # Install Claude Code hooks for context enrichment
llmkb init --non-interactive                  # Skip prompts (for CI/headless)
llmkb init /path/to/project                   # Scaffold in a specific directory

llmkb login — Authenticate

Authenticates with a user-level access token, stores it in your OS keychain, discovers accessible spaces, and writes .llmkb/spaces.yml.

llmkb login --project-space <space-uuid>      # Authenticate and set project space

The CLI will:

1. Prompt you to paste your access token (generate one from your llmkb dashboard at Settings → Access Tokens)
2. Validate the token against the server
3. Store the token in your OS keychain
4. Discover all spaces you have access to
5. Write .llmkb/spaces.yml

llmkb logout — Remove credentials

llmkb logout                                  # Remove access token from keychain

llmkb sync — Sync local files

Uploads local files to your llmkb space as knowledge sources. Uses content-addressed sync — only new and changed files are uploaded.

llmkb sync                                    # Sync current directory
llmkb sync src/                               # Sync a specific directory or file
llmkb sync --dry-run                          # Preview what would be uploaded
llmkb sync --force                            # Re-upload everything, bypassing cache
llmkb sync --watch                            # Watch for file changes and auto-sync
llmkb sync --debounce 500                     # Watch debounce in milliseconds (default: 300)
llmkb sync --json                             # Machine-readable JSON output
llmkb sync --verbose                          # Detailed output including skipped files
llmkb sync --space <space-uuid>               # Override target space

llmkb query — Search your knowledge base

Searches an llmkb space and prints ranked results from the knowledge graph.

llmkb query "your search text"                # Search the project space
llmkb query "search text" --space <space-id>  # Search a specific space
llmkb query "search text" --limit 20          # Max results (default: 10)
llmkb query "search text" --json              # Machine-readable JSON output

llmkb doctor — Diagnose configuration

Run all configuration and permission checks to verify your setup is healthy.

llmkb doctor                                  # Run full diagnostic

Checks performed:

• Config file validity (.llmkb/config.yml, .llmkb/spaces.yml)
• Backend server connectivity
• Access token validity
• Space access permissions for all configured spaces
• Related spaces synced from backend

llmkb status — Display current state

Shows version stamps, configuration summary, and access token status.

llmkb status

llmkb use — Switch project space

Sets the active project space in .llmkb/spaces.yml.

llmkb use <space-uuid>                        # Set project space

llmkb whoami — Show current user

Displays the currently authenticated user's identity.

llmkb whoami

llmkb add — Register a space

Adds a space to .llmkb/spaces.yml without authenticating.

llmkb add --space <space-uuid>                # Add a space
llmkb add --space <uuid> --name "My Space"    # Add with a display name

llmkb remove — Unregister a space

Removes a space from .llmkb/spaces.yml.

llmkb remove --space <space-uuid>             # Remove a space

llmkb update — Update project space

Updates the project space configuration in .llmkb/spaces.yml.

llmkb update --project-space <space-uuid>     # Update project space

llmkb spaces — List configured spaces

Lists all spaces registered in .llmkb/spaces.yml.

llmkb spaces                                  # List spaces
llmkb spaces --delete-all                     # Remove all space entries (requires confirmation)

llmkb hooks — Manage Claude Code hooks

Manages hooks that enrich Claude Code context with llmkb data and check sync freshness.

llmkb hooks install                           # Install hooks
llmkb hooks install --force                   # Overwrite existing hook files
llmkb hooks remove                            # Remove hooks
llmkb hooks check                             # Check whether hooks are installed

Environment Variables (Headless / CI)

In environments without a keychain (Linux servers, CI), use environment variables:

| Variable | Purpose | |----------|---------| | LLMKB_ENDPOINT | Server URL (e.g., https://llmkb.your-server.com) | | LLMKB_SPACE | Default space name for operations | | LLMKB_TOKEN | Space access token | | LLMKB_ADMIN_TOKEN | Admin token for admin operations |

Example:

export LLMKB_ENDPOINT=https://llmkb.example.com
export LLMKB_SPACE=my-project
export LLMKB_TOKEN=llmkb_abc123...

MCP Integration

The plugin registers an MCP server so Claude Code can interact with your llmkb spaces during chat sessions.

Docker stdio transport (local development — requires Docker Compose running):

{
  "mcpServers": {
    "llmkb": {
      "command": "docker",
      "args": ["compose", "--profile", "mvp", "exec", "-i", "api",
        "python", "-m", "app.mcp.stdio"]
    }
  }
}

HTTP transport (remote/production deployment):

{
  "mcpServers": {
    "llmkb": {
      "type": "url",
      "url": "https://llmkb.your-server.com/mcp"
    }
  }
}

Typical Workflow

# First-time setup
cd my-project
llmkb init
llmkb login --project-space abc123...

# Daily use
llmkb sync src/                # Sync code changes
llmkb query "auth patterns"    # Search knowledge base
llmkb doctor                   # Check everything is healthy

Configuration Files

After llmkb init, the following files are created in your project:

| File | Purpose | |------|---------| | .claude-plugin/plugin.json | Plugin metadata for Claude Code | | .mcp.json | MCP server registration | | .llmkb/spaces.yml | Space configuration (without tokens) | | .llmkb/config.yml | General plugin configuration | | .claude/skills/llmkb/*/SKILL.md | Claude Code skills (if installed with --with-skills) | | .claude/hooks/llmkb/hooks.json | Claude Code hooks (if installed with --with-hooks) |

Tokens are never stored in config files. They are stored in your OS keychain, with environment variable fallback for headless environments.

License

MIT