{"id":35542535,"url":"https://github.com/blueraai/bluera-knowledge","last_synced_at":"2026-04-01T22:00:21.163Z","repository":{"id":331347241,"uuid":"1125000403","full_name":"blueraai/bluera-knowledge","owner":"blueraai","description":"Local knowledge search for AI coding agents. Index repos, docs, and files with semantic + full-text search. Claude Code plugin \u0026 MCP server for fast, offline answers without web lookups or rate limits.","archived":false,"fork":false,"pushed_at":"2026-03-19T22:01:11.000Z","size":35987,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T11:09:09.065Z","etag":null,"topics":["ai-agents","anthropic","claue-code","cli-tool","code-search","developer-tools","documentation","embedding-model","knowledge-management","mcp","offline-first","rag","retrieval","semantic-search","typescript","vector-database"],"latest_commit_sha":null,"homepage":"https://bluera.ai/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blueraai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T01:36:44.000Z","updated_at":"2026-03-19T21:58:06.000Z","dependencies_parsed_at":"2026-01-31T20:04:57.795Z","dependency_job_id":null,"html_url":"https://github.com/blueraai/bluera-knowledge","commit_stats":null,"previous_names":["chris-bluera/bluera-knowledge"],"tags_count":155,"template":false,"template_full_name":null,"purl":"pkg:github/blueraai/bluera-knowledge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueraai%2Fbluera-knowledge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueraai%2Fbluera-knowledge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueraai%2Fbluera-knowledge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueraai%2Fbluera-knowledge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blueraai","download_url":"https://codeload.github.com/blueraai/bluera-knowledge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueraai%2Fbluera-knowledge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","claue-code","cli-tool","code-search","developer-tools","documentation","embedding-model","knowledge-management","mcp","offline-first","rag","retrieval","semantic-search","typescript","vector-database"],"created_at":"2026-01-04T05:10:53.974Z","updated_at":"2026-04-01T22:00:21.138Z","avatar_url":"https://github.com/blueraai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Bluera Knowledge\n\n[![CI](https://github.com/blueraai/bluera-knowledge/actions/workflows/ci.yml/badge.svg)](https://github.com/blueraai/bluera-knowledge/actions/workflows/ci.yml)\n![NPM Version](https://img.shields.io/npm/v/bluera-knowledge)\n![NPM Downloads](https://img.shields.io/npm/dm/bluera-knowledge)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Node](https://img.shields.io/badge/node-20.x%20%7C%2022.x-brightgreen)\n![Python](https://img.shields.io/badge/python-optional-lightgrey)\n\n\u003e 🚀 **Build a local knowledge base for your AI coding agent—dependency source code, crawled docs, and your own files, all instantly searchable.**\n\n**Two ways to use it:**\n\n| | npm Package | Claude Code Plugin |\n|--|-------------|-------------------|\n| **Install** | `npm install -g bluera-knowledge` | `/plugin install bluera-knowledge@bluera` |\n| **Interface** | CLI commands | Slash commands + MCP tools |\n| **Works with** | Any AI tool, any editor | Claude Code specifically |\n| **Best for** | CI/CD, automation, other editors | Native Claude Code integration |\n\nBoth provide the same core functionality: index repos, crawl docs, semantic search.\n\nBluera Knowledge gives AI coding agents instant local access to authoritative context:\n\n- **Dependency source code** — Clone and search the repos of dependencies you actually use\n- **Documentation** — Crawl, index, and search any docs site\n- **Your files** — Index and search local folders for project-specific knowledge\n\nAll searchable in milliseconds, no rate limits, fully offline.\n\n## 📑 Table of Contents\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand\u003c/summary\u003e\n\n- [Installation](#-installation)\n- [Why Bluera Knowledge?](#-why-bluera-knowledge)\n- [When to Query BK](#-when-claude-code-should-query-bk)\n- [Quick Start](#-quick-start)\n- [Features](#-features)\n- [How It Works](#-how-it-works)\n- [User Interface](#-user-interface)\n- [Background Jobs](#-background-jobs)\n- [Use Cases](#-use-cases)\n- [Skills for Claude Code](#-skills-for-claude-code)\n- [Data Storage](#-data-storage)\n- [Troubleshooting](#-troubleshooting)\n- [Dependencies](#-dependencies)\n- [Technologies](#-technologies)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n\u003c/details\u003e\n\n---\n\n## 📦 Installation\n\n### npm Package (CLI)\n\n```bash\n# Global install (CLI available everywhere)\nnpm install -g bluera-knowledge\n\n# Or project install\nnpm install --save-dev bluera-knowledge\n```\n\nWorks with any AI coding tool, editor, CI/CD pipeline, or automation.\n\n### Claude Code Plugin\n\n```bash\n# Add the Bluera marketplace (one-time setup)\n/plugin marketplace add blueraai/bluera-marketplace\n\n# Install the plugin (or use /plugin to browse the UI)\n/plugin install bluera-knowledge@bluera\n```\n\nAdds slash commands, MCP tools, and Skills for optimal Claude Code integration.\n\n\u003e [!NOTE]\n\u003e Setup runs automatically on first session start (installs dependencies and Playwright browser). If you see \"Setup running in background...\", wait ~30s and restart Claude Code.\n\n### Prerequisites\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Node.js | v20.x or v22.x | LTS recommended. v24+ not yet supported (native module compatibility) |\n| Build tools | - | `make` + C++ compiler (`build-essential` on Debian/Ubuntu, Xcode CLI on macOS) |\n| Python 3 | Optional | Enables code-graph features |\n\n---\n\n## ✨ Why Bluera Knowledge?\n\nWhen your AI coding assistant needs to answer \"how do I handle errors in Express middleware?\", it can:\n\n1. **Guess from training data** — might be outdated or wrong\n2. **Search the web** — slow, rate-limited, often returns blog posts instead of source\n3. **Read your local knowledge base** — authoritative, complete, instant ✅\n\nBluera Knowledge enables option 3 by building a searchable knowledge base from **three types of sources**:\n\n| Source Type | What It Does | Example |\n|------------|--------------|---------|\n| **📦 Dependency Source Code** | Clone \u0026 search library repos you actually use | Express, React, Lodash |\n| **🌐 Documentation Sites** | Crawl \u0026 index any docs site | Next.js docs, FastAPI guides |\n| **📁 Local Files** | Index project-specific content | Your docs, standards, API specs |\n\n**The result:** Your AI agent has local, instant access to authoritative information with zero rate limits:\n\n| Capability | Without | With Bluera Knowledge |\n|------------|---------|----------------------|\n| Response time | 2-5 seconds (web) | ~100ms (local) |\n| Accuracy | Uncertain | Authoritative (source code + docs) |\n| Completeness | Partial docs | Full implementation + tests + your content |\n| Rate limits | Yes | None |\n\n---\n\n## 🎯 When Claude Code Should Query BK\n\n**The simple rule: Query BK for any question about libraries, dependencies, or reference material.**\n\nBK is cheap (~100ms, no rate limits), authoritative (actual source code), and complete (includes tests and internal APIs). Claude Code should query it frequently for external code questions.\n\n### Always Query BK For:\n\n| Question Type | Examples |\n|--------------|----------|\n| **Library internals** | \"How does Express handle middleware errors?\", \"What does useEffect cleanup do?\" |\n| **API signatures** | \"What parameters does axios.create() accept?\", \"What options can I pass to Hono?\" |\n| **Error handling** | \"What errors can Zod throw?\", \"Why might this library return undefined?\" |\n| **Version behavior** | \"What changed in React 18?\", \"Is this method deprecated?\" |\n| **Configuration** | \"What config options exist for Vite?\", \"What are the defaults?\" |\n| **Testing patterns** | \"How do the library authors test this?\", \"How should I mock this?\" |\n| **Performance/internals** | \"Is this cached internally?\", \"What's the complexity?\" |\n| **Security** | \"How does this library validate input?\", \"Is this safe against injection?\" |\n| **Integration** | \"How do I integrate X with Y?\", \"What's the idiomatic way to use this?\" |\n\n### DO NOT Query BK For:\n\n| Question Type | Use Instead |\n|--------------|-------------|\n| **Your project code** | Grep/Read directly (\"Where is OUR auth middleware?\") |\n| **General concepts** | Training data (\"What is a closure?\") |\n| **Breaking news** | Web search (\"Latest React release notes\") |\n\n### Quick Pattern Matching:\n\n```\n\"How does [library] work...\"           → Query BK\n\"What does [library function] do...\"   → Query BK\n\"What options does [library] accept...\"→ Query BK\n\"What errors can [library] throw...\"   → Query BK\n\"Where is [thing] in OUR code...\"      → Grep/Read directly\n\"What is [general concept]...\"         → Training data\n```\n\n---\n\n## 🚀 Quick Start\n\n### Using Claude Code Plugin\n\n- [ ] **📦 Add a library**: `/bluera-knowledge:add-repo https://github.com/lodash/lodash`\n- [ ] **📁 Index your docs**: `/bluera-knowledge:add-folder ./docs --name=project-docs`\n- [ ] **🔍 Test search**: `/bluera-knowledge:search \"deep clone object\"`\n- [ ] **📋 View stores**: `/bluera-knowledge:stores`\n\n\u003e [!TIP]\n\u003e Not sure which libraries to index? Use `/bluera-knowledge:suggest` to analyze your project's dependencies.\n\n### Using CLI (npm package)\n\n```bash\n# Add a library\nbluera-knowledge store create lodash --type repo --source https://github.com/lodash/lodash\n\n# Index your docs\nbluera-knowledge store create project-docs --type file --source ./docs\n\n# Test search\nbluera-knowledge search \"deep clone object\"\n\n# View stores\nbluera-knowledge store list\n```\n\n---\n\n## ✨ Features\n\n### 🎯 Core Features\n\n- **🔬 Smart Dependency Analysis** - Automatically scans your project to identify which libraries are most heavily used by counting import statements across all source files\n- **📊 Usage-Based Suggestions** - Ranks dependencies by actual usage frequency, showing you the top 5 most-imported packages with import counts and file counts\n- **🔍 Automatic Repository Discovery** - Queries package registries (NPM, PyPI, crates.io, Go modules) to automatically find GitHub repository URLs\n- **📦 Git Repository Indexing** - Clones and indexes dependency source code for both semantic search and direct file access\n- **📁 Local Folder Indexing** - Indexes any local content - documentation, standards, reference materials, or custom content\n- **🌐 Web Crawling** - Crawl and index web pages using Node.js Playwright - convert documentation sites to searchable markdown\n\n### 🔍 Search Modes\n\n- **🧠 Vector Search** - AI-powered semantic search with relevance ranking\n- **📂 File Access** - Direct Grep/Glob operations on cloned source files\n\n### 🗺️ Code Graph Analysis\n\n- **📊 Code Graph Analysis** - During indexing, builds a graph of code relationships (calls, imports, extends) to provide usage context in search results - shows how many callers/callees each function has\n- **🌐 Multi-Language Support** - Full AST parsing for JavaScript, TypeScript, Python, Rust, and Go; indexes code in any language\n- **🔌 MCP Integration** - Exposes all functionality as Model Context Protocol tools for AI coding agents\n\n### 🌍 Language-Specific Features\n\nWhile bluera-knowledge indexes and searches code in any language, certain advanced features are language-specific:\n\n| Language | Code Graph | Call Analysis | Import Tracking | Method Tracking |\n|----------|------------|---------------|-----------------|-----------------|\n| **TypeScript/JavaScript** | ✅ Full Support | ✅ Functions \u0026 Methods | ✅ Full | ✅ Class Methods |\n| **Python** | ✅ Full Support | ✅ Functions \u0026 Methods | ✅ Full | ✅ Class Methods |\n| **Rust** | ✅ Full Support | ✅ Functions \u0026 Methods | ✅ Full | ✅ Struct/Trait Methods |\n| **Go** | ✅ Full Support | ✅ Functions \u0026 Methods | ✅ Full | ✅ Struct/Interface Methods |\n| **ZIL** | ✅ Full Support | ✅ Routines | ✅ INSERT-FILE | ✅ Objects/Rooms |\n| **Other Languages** | ⚠️ Basic Support | ❌ | ❌ | ❌ |\n\n\u003e [!NOTE]\n\u003e Code graph features enhance search results by showing usage context (e.g., \"this function is called by 15 other functions\"), but all languages benefit from vector search and full-text search capabilities.\n\n### 🔌 Custom Language Support\n\nBluera Knowledge provides an extensible adapter system for adding full graph support to any language. The built-in ZIL adapter (for Infocom/Zork-era source code) demonstrates this capability.\n\n**What adapters provide:**\n- **Smart chunking** - Split files by language constructs (functions, classes, objects)\n- **Symbol extraction** - Parse definitions with signatures and line numbers\n- **Import tracking** - Resolve include/import relationships\n- **Call graph analysis** - Track function calls with special form filtering\n\n**Built-in adapters:**\n| Language | Extensions | Symbols | Imports |\n|----------|------------|---------|---------|\n| ZIL | `.zil`, `.mud` | ROUTINE, OBJECT, ROOM, GLOBAL, CONSTANT | INSERT-FILE |\n\n**Example - ZIL indexing:**\n```bash\n# Index a Zork source repository\nbluera-knowledge store create zork1 --type repo --source https://github.com/historicalsource/zork1\n\n# Search for routines\nbluera-knowledge search \"V-LOOK routine\" --stores zork1\n```\n\n---\n\n## 🎯 How It Works\n\nThe plugin provides AI agents with **four complementary search capabilities**:\n\n### 🔍 1. Semantic Vector Search\n**AI-powered search across all indexed content**\n\n- Searches by meaning and intent, not just keywords\n- Uses embeddings to find conceptually similar content\n- Ideal for discovering patterns and related concepts\n\n### 📝 2. Full-Text Search (FTS)\n**Fast keyword and pattern matching**\n\n- Traditional text search with exact matching\n- Supports regex patterns and boolean operators\n- Best for finding specific terms or identifiers\n\n### ⚡ 3. Hybrid Mode (Recommended)\n**Combines vector and FTS search**\n\n- Merges results from both search modes with weighted ranking\n- Balances semantic understanding with exact matching\n- Provides best overall results for most queries\n\n### 📂 4. Direct File Access\n**Traditional file operations on cloned sources**\n\n- Provides file paths to cloned repositories\n- Enables Grep, Glob, and Read operations on source files\n- Supports precise pattern matching and code navigation\n- Full access to complete file trees\n\n\u003cdetails\u003e\n\u003csummary\u003e💡 \u003cb\u003eHow Commands Work\u003c/b\u003e\u003c/summary\u003e\n\nWhen you use `/bluera-knowledge:` commands, here's what happens:\n\n1. **You issue a command** - Type `/bluera-knowledge:stores` or similar in Claude Code\n2. **Claude Code receives instructions** - The command provides step-by-step instructions for Claude Code\n3. **Claude Code executes MCP tools** - Behind the scenes, Claude Code uses `mcp__bluera-knowledge__*` tools\n4. **Results are formatted** - Claude Code formats and displays the output directly to you\n\n**Example Flow:**\n```\nYou: /bluera-knowledge:stores\n  ↓\nCommand file instructs Claude Code to use execute(\"stores\")\n  ↓\nMCP tool queries LanceDB for store metadata\n  ↓\nClaude Code formats results as a table\n  ↓\nYou see: Beautiful table of all your knowledge stores\n```\n\nThis architecture means commands provide a clean user interface while MCP tools handle the backend operations.\n\u003c/details\u003e\n\n---\n\n## 🎨 User Interface\n\n### 👤 User Commands\n**You manage knowledge stores through `/bluera-knowledge:` commands:**\n\n- 🔬 Analyze your project to find important dependencies\n- 📦 Add Git repositories (dependency source code)\n- 📁 Add local folders (documentation, standards, etc.)\n- 🌐 Crawl web pages and documentation\n- 🔍 Search across all indexed content\n- 🔄 Manage and re-index stores\n\n### 🤖 MCP Tools\n**AI agents access knowledge through Model Context Protocol (3 tools for minimal context overhead):**\n\n| Tool | Purpose |\n|------|---------|\n| `search` | 🔍 Semantic vector search across all stores (includes store paths for direct file access) |\n| `get_full_context` | 📖 Retrieve complete code context by result ID or file path |\n| `execute` | ⚡ Meta-tool for store/job management commands |\n\nThe `execute` tool consolidates store and job management into a single tool with subcommands:\n- **Store commands**: `stores`, `store:info`, `store:create`, `store:index`, `store:delete`, `stores:pull`\n- **Job commands**: `jobs`, `job:status`, `job:cancel`\n- **Help**: `help`, `commands`\n\n---\n\n## ⚙️ Background Jobs\n\n\u003e [!TIP]\n\u003e Long-running operations (git clone, indexing) run in the background, allowing you to continue working while they complete.\n\n### 🔄 How It Works\n\nWhen you add a repository or index content:\n\n1. **⚡ Instant Response** - Operation starts immediately and returns a job ID\n2. **🔄 Background Processing** - Indexing runs in a separate process\n3. **📊 Progress Updates** - Check status anytime with `/bluera-knowledge:check-status`\n4. **🔔 Auto-Notifications** - Active jobs appear automatically in context\n\n### 📝 Example Workflow\n\n```bash\n# Add a large repository (returns immediately with job ID)\n/bluera-knowledge:add-repo https://github.com/facebook/react\n\n# Output:\n# ✓ Created store: react (a1b2c3d4...)\n# 🔄 Indexing started in background\n#    Job ID: job_abc123def456\n#\n# Check status with: /bluera-knowledge:check-status job_abc123def456\n\n# Check progress anytime\n/bluera-knowledge:check-status job_abc123def456\n\n# Output:\n# Job Status: job_abc123def456\n# Status:   running\n# Progress: ███████████░░░░░░░░░ 45%\n# Message:  Indexed 562/1,247 files\n\n# View all active jobs\n/bluera-knowledge:check-status\n\n# Cancel if needed\n/bluera-knowledge:cancel job_abc123def456\n```\n\n### 🚀 Performance\n\nBackground jobs include significant performance optimizations:\n\n- **⚡ Parallel Embedding** - Batch processes up to 32 chunks simultaneously\n- **📂 Parallel File I/O** - Processes multiple files concurrently (configurable, default: 4)\n- **🔓 Non-Blocking** - Continue working while indexing completes\n- **📊 Progress Tracking** - Real-time updates on files processed and progress percentage\n- **🧹 Auto-Cleanup** - Completed/stale jobs are cleaned up automatically\n\n---\n\n## 🎯 Use Cases\n\n### Dependency Source Code\n\nProvide AI agents with canonical dependency implementation details:\n\n```bash\n/bluera-knowledge:suggest\n/bluera-knowledge:add-repo https://github.com/expressjs/express\n\n# AI agents can now:\n# - Semantic search: \"middleware error handling\"\n# - Direct access: Grep/Glob through the cloned express repo\n```\n\n### Project Documentation\n\nMake project-specific documentation available:\n\n```bash\n/bluera-knowledge:add-folder ./docs --name=project-docs\n/bluera-knowledge:add-folder ./architecture --name=architecture\n\n# AI agents can search across all documentation or access specific files\n```\n\n### Coding Standards\n\nProvide definitive coding standards and best practices:\n\n```bash\n/bluera-knowledge:add-folder ./company-standards --name=standards\n/bluera-knowledge:add-folder ./api-specs --name=api-docs\n\n# AI agents reference actual company standards, not generic advice\n```\n\n### Mixed Sources\n\nCombine canonical library code with project-specific patterns:\n\n```bash\n/bluera-knowledge:add-repo https://github.com/facebook/react --name=react\n/bluera-knowledge:add-folder ./docs/react-patterns --name=react-patterns\n\n# Search across both dependency source and team patterns\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### Quick Diagnostics\n\nRun `/bluera-knowledge:doctor` to diagnose common issues. This checks:\n- Build tools (make/gcc) - required for native modules\n- Node.js installation\n- Plugin dependencies (node_modules)\n- MCP wrapper installation\n- Python 3 (optional, for embeddings)\n- Playwright browser (optional, for web crawling)\n\nWorks even when MCP is broken (uses Bash tool directly).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Command not found or not recognized\u003c/b\u003e\u003c/summary\u003e\n\nEnsure the plugin is installed and enabled:\n\n```bash\n/plugin list\n/plugin enable bluera-knowledge\n```\n\nIf the plugin isn't listed, install it:\n\n```bash\n/plugin marketplace add blueraai/bluera-marketplace\n/plugin install bluera-knowledge@bluera\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔌 MCP server shows as \"failed\" in /plugin\u003c/b\u003e\u003c/summary\u003e\n\nIf the MCP server shows as failed after installation:\n\n1. **Run `/bluera-knowledge:doctor`** - This diagnoses the most common issues\n2. **Restart Claude Code** - MCP servers require a restart to initialize\n3. **Check logs:** Run `/logs errors` to see recent errors or `/logs module bootstrap` for startup logs\n4. **Check status:** Run `/mcp` to see connection status\n5. **Reinstall:** Try `/plugin uninstall bluera-knowledge` then `/plugin install bluera-knowledge@bluera`\n\n**Common MCP failure causes:**\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `npm ERR! ERESOLVE` in logs | Peer dependency conflict | Fixed in v0.22.6+ with npm flag |\n| Old plugin version running | Multiple cached versions | Fixed in v0.22.7+ (version sorting) |\n| `make not found` | Missing build tools | Install `build-essential` (Linux) |\n| Compilation errors on Node 24 | V8 API changes | Use Node.js v20.x or v22.x |\n\nIf the issue persists, check that Claude Code is v2.0.65 or later (earlier versions had MCP loading bugs).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🌐 Web crawling fails\u003c/b\u003e\u003c/summary\u003e\n\nCheck Playwright browser installation:\n\n```bash\nnpx playwright install chromium\n```\n\nThe plugin attempts to auto-install Playwright browsers on first use, but manual installation may be needed in some environments.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔍 Search returns no results\u003c/b\u003e\u003c/summary\u003e\n\n1. Verify store exists: `/bluera-knowledge:stores`\n2. Check store is indexed: `/bluera-knowledge:index \u003cstore-name\u003e`\n3. Try broader search terms\n4. Verify you're searching the correct store with `--stores=\u003cname\u003e`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⚠️ \"Model mismatch\" error\u003c/b\u003e\u003c/summary\u003e\n\nThis error occurs when a store was indexed with a different embedding model than the current configuration. As of v0.20+, stores are indexed with `bge-small-en-v1.5` (previously `all-MiniLM-L6-v2`).\n\n**Solution:** Reindex the affected store:\n\n```bash\n/bluera-knowledge:index \u003cstore-name\u003e\n```\n\n**Check model status for all stores:**\n\n```bash\n# Via MCP execute command\nexecute stores:check-models\n```\n\nThis lists all stores with their embedding model and flags any that need reindexing.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❓ \"Store not found\" error\u003c/b\u003e\u003c/summary\u003e\n\nList all stores to see available names and IDs:\n\n```bash\n/bluera-knowledge:stores\n```\n\nUse the exact store name or ID shown in the table.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔨 Native module compilation fails (Node.js v24)\u003c/b\u003e\u003c/summary\u003e\n\ntree-sitter and lancedb require native module compilation. Node.js v24 introduced V8 API changes that break these modules.\n\n**Solution:** Use Node.js v20.x or v22.x (LTS versions):\n\n```bash\n# Using nvm\nnvm install 22\nnvm use 22\n```\n\nRun `/bluera-knowledge:doctor` to verify your environment.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐧 Linux: \"make not found\" or build errors\u003c/b\u003e\u003c/summary\u003e\n\nNative modules require build tools:\n\n```bash\n# Debian/Ubuntu\nsudo apt install build-essential\n\n# Fedora/RHEL\nsudo dnf groupinstall \"Development Tools\"\n```\n\nThen restart Claude Code for auto-setup to complete.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⏱️ Indexing is slow or fails\u003c/b\u003e\u003c/summary\u003e\n\nLarge repositories (10,000+ files) take longer to index. If indexing fails:\n\n1. Check available disk space\n2. Ensure the source repository/folder is accessible\n3. For repo stores, verify git is installed: `git --version`\n4. Check for network connectivity (for repo stores)\n5. Check logs for errors: `/logs errors` or `/logs search \"index\"`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🤖 \"Claude CLI not found\" during crawl\u003c/b\u003e\u003c/summary\u003e\n\nThis means intelligent crawling is unavailable. The crawler will automatically use simple BFS mode instead.\n\nTo enable intelligent crawling with `--crawl` and `--extract`:\n1. Install Claude Code: https://claude.com/code\n2. Ensure `claude` command is in PATH: `which claude`\n\nSimple mode still crawls effectively—it just doesn't use AI to select which pages to crawl or extract specific content.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 How to view logs for debugging\u003c/b\u003e\u003c/summary\u003e\n\nThe plugin logs all MCP server operations to `.bluera/bluera-knowledge/logs/app.log` (relative to project root).\n\n**View logs using the `/logs` command:**\n\n```bash\n/logs              # Watch logs in real-time (tail -f)\n/logs view 50      # View last 50 log entries\n/logs errors       # Show only error-level logs\n/logs module mcp-store  # Filter by module (mcp-server, mcp-store, mcp-execute, mcp-job, mcp-sync, bootstrap)\n/logs search \"pattern\"  # Search for a pattern\n```\n\n**Log modules:**\n- `bootstrap` - MCP server startup and dependency installation\n- `mcp-server` - Core MCP server operations\n- `mcp-store` - Store create/list/delete operations\n- `mcp-search` - Search queries and results\n- `mcp-execute` - Meta-tool command execution\n- `mcp-job` - Background job status\n- `mcp-sync` - Store sync operations\n\n**Manual access:**\n```bash\ntail -f .bluera/bluera-knowledge/logs/app.log\n```\n\nLogs are JSON formatted (NDJSON) and can be processed with `jq` for pretty-printing.\n\u003c/details\u003e\n\n---\n\n## 🔧 Dependencies\n\n**Required for Web Crawling:**\n- **🎭 Playwright Chromium** - Required for headless browser crawling (auto-installed on first session)\n\n**Optional:**\n- **🐍 Python 3.8+** - Only needed for Python AST parsing in code-graph features (not required for web crawling)\n\n**Setup (automatic):**\n\nSetup runs automatically on first session start. This installs:\n- ✅ MCP wrapper script\n- ✅ Node.js dependencies (via bun/npm)\n- ✅ Playwright Chromium browser binaries\n\nIf you see \"Setup running in background...\", wait ~30s and restart Claude Code.\n\n**Manual setup (if auto-setup fails):**\n\n```bash\nnpx playwright install chromium\n```\n\n\u003e [!NOTE]\n\u003e Web crawling uses Node.js Playwright directly—no Python dependencies required. The default mode uses headless browser for maximum compatibility with JavaScript-rendered sites. Use `--fast` for static sites when speed is critical.\n\n**Update Plugin:**\n```bash\n/plugin update bluera-knowledge\n```\n\n---\n\n## 🎓 Skills for Claude Code\n\n\u003e [!NOTE]\n\u003e Skills are a Claude Code-specific feature. They're automatically loaded when using the plugin but aren't available when using the npm package directly.\n\nBluera Knowledge includes built-in Skills that teach Claude Code how to use the plugin effectively. Skills provide procedural knowledge that complements the MCP tools.\n\n### 📚 Available Skills\n\n#### `knowledge-search`\nTeaches the two approaches for accessing dependency sources:\n- Vector search via MCP/slash commands for discovery\n- Direct Grep/Read access to cloned repos for precision\n\n**When to use:** Understanding how to query indexed libraries\n\n#### `when-to-query`\nDecision guide for when to query BK stores vs using Grep/Read on current project.\n\n**When to use:** Deciding whether a question is about libraries or your project code\n\n#### `advanced-workflows`\nMulti-tool orchestration patterns for complex operations.\n\n**When to use:** Progressive library exploration, adding libraries, handling large results\n\n#### `search-optimization`\nGuide on search parameters and progressive detail strategies.\n\n**When to use:** Optimizing search results, choosing the right intent and detail level\n\n#### `store-lifecycle`\nBest practices for creating, indexing, and managing stores.\n\n**When to use:** Adding new stores, understanding when to use repo/folder/crawl\n\n### 🔄 MCP + Skills Working Together\n\nSkills teach **how** to use the MCP tools effectively:\n- MCP provides the **capabilities** (search, get_full_context, execute commands)\n- Skills provide **procedural knowledge** (when to use which tool, best practices, workflows)\n\nThis hybrid approach reduces unnecessary tool calls and context usage while maintaining universal MCP compatibility.\n\n**Example:**\n- MCP tool: `search(query, intent, detail, limit, stores)`\n- Skill teaches: Which `intent` for your question type, when to use `detail='minimal'` vs `'full'`, how to narrow with `stores`\n\nResult: Fewer tool calls, more accurate results, less context consumed.\n\n### 🎯 Skill Auto-Activation\n\nSkills can automatically suggest themselves when your prompt matches certain patterns.\n\n**Toggle via slash command:**\n- `/bluera-knowledge:skill-activation` - Show current status\n- `/bluera-knowledge:skill-activation on` - Enable (default)\n- `/bluera-knowledge:skill-activation off` - Disable\n- `/bluera-knowledge:skill-activation config` - Toggle individual skills\n\n**How it works:**\nWhen enabled, a UserPromptSubmit hook analyzes your prompt for patterns like:\n- \"How does [library] work?\" → suggests `knowledge-search`\n- \"Should I grep or search?\" → suggests `when-to-query`\n- \"Too many results\" → suggests `search-optimization`\n- \"Multi-step workflow\" → suggests `advanced-workflows`\n- \"Add/delete store\" → suggests `store-lifecycle`\n\nClaude evaluates each suggestion and invokes relevant skills before answering. Users who already use BK terminology are excluded (they already know the tool).\n\n**Configuration stored in:** `.bluera/bluera-knowledge/skill-activation.json` (relative to project root)\n\n---\n\n## 💾 Data Storage\n\nKnowledge stores are stored in your project root:\n\n```\n\u003cproject-root\u003e/.bluera/bluera-knowledge/\n├── data/\n│   ├── repos/\u003cstore-id\u003e/       # Cloned Git repositories\n│   ├── documents_*.lance/      # Vector indices (Lance DB)\n│   └── stores.json             # Store registry\n├── stores.config.json          # Store definitions (git-committable!)\n└── config.json                 # Configuration\n```\n\n### 📋 Store Definitions (Team Sharing)\n\nStore definitions are automatically saved to `.bluera/bluera-knowledge/stores.config.json`. This file is designed to be **committed to git**, allowing teams to share store configurations.\n\n**Example `stores.config.json`:**\n```json\n{\n  \"version\": 1,\n  \"stores\": [\n    { \"type\": \"file\", \"name\": \"my-docs\", \"path\": \"./docs\" },\n    { \"type\": \"repo\", \"name\": \"react\", \"url\": \"https://github.com/facebook/react\" },\n    { \"type\": \"web\", \"name\": \"api-docs\", \"url\": \"https://api.example.com/docs\", \"depth\": 2 }\n  ]\n}\n```\n\nWhen a teammate clones the repo, they can run `/bluera-knowledge:sync` to recreate all stores locally.\n\n### 🚫 Recommended `.gitignore` Patterns\n\nWhen you first create a store, the plugin automatically updates your `.gitignore` with:\n\n```gitignore\n# Bluera Knowledge - data directory (not committed)\n.bluera/\n!.bluera/bluera-knowledge/\n!.bluera/bluera-knowledge/stores.config.json\n```\n\nThis ensures:\n- Vector indices and cloned repos are **NOT committed** (they're large and can be recreated)\n- Store definitions **ARE committed** (small JSON file for team sharing)\n\n---\n\n## 🔬 Technologies\n\n- **🔌 Claude Code Plugin System** with MCP server\n- **✅ Runtime Validation** - [Zod](https://github.com/colinhacks/zod) schemas for Python-TypeScript boundary\n- **🌳 AST Parsing** - [@babel/parser](https://github.com/babel/babel) for JS/TS, Python AST module, [tree-sitter](https://github.com/tree-sitter/tree-sitter) for Rust and Go\n- **🗺️ Code Graph** - Static analysis of function calls, imports, and class relationships\n- **🧠 Semantic Search** - AI-powered vector embeddings with [LanceDB](https://github.com/lancedb/lancedb)\n- **📦 Git Operations** - Native git clone\n- **💻 CLI** - [Commander.js](https://github.com/tj/commander.js)\n- **🕷️ Web Crawling** - [Playwright](https://github.com/microsoft/playwright) (Node.js headless browser) with [Cheerio](https://github.com/cheeriojs/cheerio) (HTML parsing)\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [CLI Reference](docs/cli.md) | Complete CLI commands, options, and usage examples |\n| [MCP Integration](docs/mcp-integration.md) | MCP server configuration and tool documentation |\n| [Commands Reference](docs/commands.md) | All slash commands with parameters and examples |\n| [Crawler Architecture](docs/crawler-architecture.md) | How the intelligent web crawler works |\n| [Token Efficiency](docs/token-efficiency.md) | How BK reduces token consumption vs web search |\n| [CONTRIBUTING](CONTRIBUTING.md) | Development setup, testing, and release process |\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and release process.\n\n---\n\n## 📄 License\n\nMIT - See [LICENSE](./LICENSE) for details.\n\n## 🙏 Acknowledgments\n\nThis project includes software developed by third parties. See [NOTICE](./NOTICE) for full attribution.\n\nKey dependencies:\n- **[Playwright](https://github.com/microsoft/playwright)** - Headless browser for web crawling (Apache-2.0)\n- **[LanceDB](https://github.com/lancedb/lancedb)** - Vector database (Apache-2.0)\n- **[Hugging Face Transformers](https://github.com/huggingface/transformers.js)** - Embeddings (Apache-2.0)\n- **[Cheerio](https://github.com/cheeriojs/cheerio)** - HTML parsing (MIT)\n\n---\n\n## 💬 Support\n\n- **🐛 Issues**: [GitHub Issues](https://github.com/blueraai/bluera-knowledge/issues)\n- **📚 Documentation**: [Claude Code Plugins](https://code.claude.com/docs/en/plugins)\n- **📝 Changelog**: [CHANGELOG.md](./CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueraai%2Fbluera-knowledge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblueraai%2Fbluera-knowledge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueraai%2Fbluera-knowledge/lists"}