@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

Local Development

By default, llmkb init points the plugin at the production endpoint (https://api.llmkb.ai). When developing against a local llmkb server (Docker Compose stack, localhost:<port>, staging URL, etc.), pass --endpoint at init time:

llmkb init --endpoint http://localhost:8000

This writes the URL into both .llmkb/config.yml (llmkb_base_url:) and .mcp.json (mcp-remote URL) consistently — no manual file editing, no risk of the two files drifting apart.

⚠️ Use the API port, not the web UI port. The plugin talks directly to the FastAPI backend. Common defaults:

| Stack | API URL | |-------|---------| | Local FastAPI dev (uvicorn app.main:app --reload) | http://localhost:8000 | | Docker Compose (host-side, FastAPI exposed) | http://localhost:8000 | | Docker Compose (via Nuxt proxy) | http://localhost:3011 | | Nuxt-only dev server (web UI, no API) | do not use — the plugin will 404 |

The web UI at http://localhost:3010 serves the Nuxt frontend, not the API. Pointing the plugin at :3010 returns 404 Page not found: /api/v1/auth/me even with a valid token.

After init, run llmkb doctor to verify connectivity, then llmkb login --project-space <uuid> to authenticate against the local backend.

Re-pointing an existing project

To switch an already-initialized project to a different endpoint, re-run init --endpoint:

llmkb init --endpoint http://localhost:8001   # or any other URL

The --endpoint flag bypasses the version-stamp idempotency check so the change takes effect on re-run.

Testing a local build before publishing

If you're iterating on the plugin source and want to validate the build before running npm publish, two paths from fastest → most thorough:

1. Run dist/cli.js directly — no install needed. The bundled output is byte-identical to what npm ships:

# from anywhere — pass an absolute path to your local dist
node plugins/claude-code/dist/cli.js init --endpoint http://localhost:8000

# verify
cat .llmkb/config.yml   # expect: llmkb_base_url: http://localhost:8000
cat .mcp.json           # expect: "mcp-remote", "http://localhost:8000/mcp/"

Use this for quick smoke tests against an already-running FastAPI dev server.

2. npm pack + tarball inspection — catches the class of bug where your edit landed in src/ but the package.json files allowlist excluded it from the published tarball. This is the publish dry-run:

cd plugins/claude-code
pnpm build                              # ensure dist/ is fresh
mkdir -p build                          # npm pack won't auto-create the dir
npm pack --pack-destination ./build     # writes build/llmkb-claude-code-<version>.tgz

# Eyeball the file list — must include dist/cli.js, dist/mcp-stdio.js,
# lib/types.js, CHANGELOG.md, README.md. Must NOT include src/, tests/,
# node_modules/, tsconfig.json, build/, or *.tgz.
tar -tzf build/llmkb-claude-code-*.tgz | sort

# Optional: install from the local tarball to overwrite the global install
npm install -g ./build/llmkb-claude-code-*.tgz
llmkb init --help | grep endpoint       # confirm the flag is registered

# Cleanup
rm -rf build

build/ and *.tgz are in both .gitignore and .npmignore, so the tarball never slips into a commit or a future published version. npm publish ignores --pack-destination entirely — it reads the manifest directly and pushes to the registry without touching your local files.

If the tarball composition looks right and llmkb init --help shows --endpoint, npm publish is the only thing left.

Manual file edit (fallback)

If you can't use --endpoint (e.g., you're updating a project that was scaffolded by an older plugin version), edit two files:

1. .llmkb/config.yml — set llmkb_base_url:

# from: https://api.llmkb.ai
llmkb_base_url: http://localhost:8000

2. .mcp.json — update the args to point mcp-remote at your local server:

{
  "mcpServers": {
    "llmkb": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp/"
      ]
    }
  }
}

Tip: if you also need to override the token stored in .mcp.json's MCP_REMOTE_HEADERS env var, run llmkb login after editing config.yml — login reads the endpoint from config.yml and rewrites both .mcp.json and .llmkb/spaces.yml against the new URL.

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 --endpoint <url>                   # Override llmkb_base_url + .mcp.json endpoint in one step (recommended for local dev)
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, fetches the project's related spaces (never the full accessible-spaces list — see M3.6-T3), and writes .llmkb/spaces.yml and .mcp.json.

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 (against llmkb_base_url from .llmkb/config.yml, or https://api.llmkb.ai by default)
3. Store the token in your OS keychain
4. Fetch the project's related spaces via GET /api/spaces/{id}/relations
5. Write .llmkb/spaces.yml and update .mcp.json's MCP_REMOTE_HEADERS

If GET /api/spaces/{id}/relations fails or returns no related spaces, login writes the project-only scope with sync_pending: true — run llmkb spaces sync-related to retry.

llmkb login --guest — Guest mode (M3.6-T17, v0.3.1+)

Authenticates with a user-level access token without a project space. Grants read-only access to public spaces only (visibility='public') — no project, no related, no write/sync.

llmkb login --guest                             # Authenticate as guest (public tier only)
llmkb login --guest --force                     # Overwrite an existing project_space

Use this when you want to try llmkb without creating a project space, or when you only need to query public spaces. Add individual public spaces to your scope:

llmkb spaces add --list                         # Show available public spaces (slug + id)
llmkb spaces add --public <slug-or-id>          # Add a public space to your scope

Guest sessions are read-only — llmkb sync / llmkb watch refuse to upload. Run llmkb login (without --guest) to upgrade to a full project session.

Upgrade path (--force overwrites guest config): switching from a guest session to a project session requires --force to drop the guest's public_spaces[]. Without --force, the upgrade is refused to prevent silent scope loss.

llmkb login --project-space <space-uuid> --force   # Drop guest public_spaces[] + print warning

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"
    }
  }
}

Using in Claude Code Chat

Once configured, llmkb tools are automatically available in Claude Code conversations. Claude can search, read, explore, and write your knowledge base during any session.

How It Works

1. The .mcp.json file registers the llmkb MCP server with Claude Code
2. Claude Code connects to your llmkb server and discovers all available tools
3. During chat, Claude decides when to call llmkb tools based on your messages
4. Results are returned inline — Claude reads them and responds naturally

You don't need to invoke tools manually. Simply describe what you want in natural language:

> search my knowledge base for authentication patterns
> read the wiki page about data fetching in Nuxt
> show me the relationship graph for the UserService entity
> synthesize an answer comparing useFetch and $fetch

Available Tools

The MCP server exposes these tool categories (29 tools total):

| Category | Tools | Use In Chat | |----------|-------|-------------| | Search | space_search, space_search_all, code_search | "search for <topic>" | | Read | space_read, space_answer, space_synthesize | "read the page about <topic>" | | Graph | space_graph, space_trace, space_entity_relations, space_cypher | "show me the graph for <entity>" | | Code | code_context, code_graph, code_impact | "what depends on <function>?" | | Browse | space_list_entities, space_list_wiki_pages, space_guide, space_schema | "list all entities", "give me an overview" | | Write | space_entities, space_write | "create an entity for <concept>" | | Metadata | space_history, space_provenance, space_impact | "what changed?", "what does this affect?" |

Skills (Optional)

If you installed skills with llmkb init --with-skills, guided workflows are available via slash commands. Skills wrap the raw MCP tools into structured, multi-step interactions:

| Skill | Command | What It Does | |-------|---------|--------------| | llmkb-query | /llmkb-query | Search your knowledge base with guided follow-up questions | | llmkb-exploring | /llmkb-exploring | Explore code relationships, callers, and execution flows | | llmkb-admin | /llmkb-admin | Manage spaces, access tokens, and configuration | | llmkb-guide | /llmkb-guide | Get an overview of your space — entities, clusters, recent changes | | llmkb-sync | /llmkb-sync | Check sync status and trigger file synchronization |

Project Space

The --project-space flag during llmkb login sets the default space that Claude queries. This is the space your project's code belongs to — where wiki pages live, entities are stored, and search results come from.

If your project draws from multiple spaces (e.g., a frontend code space and a docs space), use llmkb add --space <uuid> to register additional spaces. Claude will query all registered spaces when you ask a question.

browse_public opt-in (M3.6-T2.1)

.llmkb/spaces.yml accepts an optional browse_public: true flag. When set, the llmkb-mcp stdio wrapper performs one additional startup fetch against the backend's narrow GET /api/v1/spaces/public endpoint and treats every public-space ID as also-allowed in addition to your project's related spaces.

# .llmkb/spaces.yml
project_space:
  - id: "b6087faa-..."
spaces:
  - id: "c599f13a-..."   # a private related space (required membership)
browse_public: true       # opt-in to querying any public space (M3.6-T2.1)

What llmkb doctor reports when the opt-in is on:

5. Scope verification
  ✔ Scope verified: 2 related space(s) confirmed.
  ℹ browse_public: true
    public_spaces: 47 id(s) loaded from /api/v1/spaces/public

Critical security notes — read before enabling:

• Default false is bit-identical to the M3.6-T3 strict gate. No public-list fetch is made. Leave it off unless you need to query public docs from a private project.
• Widens ONLY to public spaces (visibility='public'). Private IDs in spaces[] are still strictly rejected — the flag does NOT auto-allow private IDs.
• Public-list fetch failure is a hard fail (exit code 3). The wrapper refuses to start rather than silently falling back to the strict scope. Treat it as a backend outage.
• The endpoint is narrow. Returns only {space_id, space_name, slug, visibility} for visibility='public' AND is_deleted=false rows — no membership, role, or PII.
• Never set automatically. A user must hand-edit spaces.yml to enable it. llmkb init / login never set this flag.

Local-dev testing recipe (M3.6-T2.1)

When iterating on the opt-in against a local or staging backend:

# 1. Hand-edit .llmkb/spaces.yml to add the flag
echo "browse_public: true" >> .llmkb/spaces.yml

# 2. Restart the MCP server so the gate re-runs the public-list fetch
#    (the fetch happens once at startup; not per-call)

# 3. Confirm scope + public count
llmkb doctor            # expect: browse_public: true + public_spaces: N

# 4. Query a public space by ID
llmkb query "auth patterns" --space <public-space-uuid>

# 5. Verify the wrapper exits 3 on backend outage
#    (point at an unreachable endpoint; the gate refuses to start)

To revert to the strict M3.6-T3 default (recommended for private repos that don't need public docs):

# Either delete the flag, or set it explicitly to false
sed -i '' '/^browse_public:/d' .llmkb/spaces.yml
# OR
echo "browse_public: false" >> .llmkb/spaces.yml

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