bluera-knowledge
Advanced tools
🚀 Build a local knowledge base for your AI coding agent—dependency source code, crawled docs, and your own files, all instantly searchable.
Two ways to use it:
| npm Package | Claude Code Plugin | |
|---|---|---|
| Install | npm install -g bluera-knowledge | /plugin install bluera-knowledge@bluera |
| Interface | CLI commands | Slash commands + MCP tools |
| Works with | Any AI tool, any editor | Claude Code specifically |
| Best for | CI/CD, automation, other editors | Native Claude Code integration |
Both provide the same core functionality: index repos, crawl docs, semantic search.
Bluera Knowledge gives AI coding agents instant local access to authoritative context:
All searchable in milliseconds, no rate limits, fully offline.
# Global install (CLI available everywhere)
npm install -g bluera-knowledge
# Or project install
npm install --save-dev bluera-knowledge
Works with any AI coding tool, editor, CI/CD pipeline, or automation.
# Add the Bluera marketplace (one-time setup)
/plugin marketplace add blueraai/bluera-marketplace
# Install the plugin (or use /plugin to browse the UI)
/plugin install bluera-knowledge@bluera
Adds slash commands, MCP tools, and Skills for optimal Claude Code integration.
[!NOTE] 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.
| Requirement | Version | Notes |
|---|---|---|
| Node.js | v20.x or v22.x | LTS recommended. v24+ not yet supported (native module compatibility) |
| Build tools | - | make + C++ compiler (build-essential on Debian/Ubuntu, Xcode CLI on macOS) |
| Python 3 | Optional | Enables code-graph features |
When your AI coding assistant needs to answer "how do I handle errors in Express middleware?", it can:
Bluera Knowledge enables option 3 by building a searchable knowledge base from three types of sources:
| Source Type | What It Does | Example |
|---|---|---|
| 📦 Dependency Source Code | Clone & search library repos you actually use | Express, React, Lodash |
| 🌐 Documentation Sites | Crawl & index any docs site | Next.js docs, FastAPI guides |
| 📁 Local Files | Index project-specific content | Your docs, standards, API specs |
The result: Your AI agent has local, instant access to authoritative information with zero rate limits:
| Capability | Without | With Bluera Knowledge |
|---|---|---|
| Response time | 2-5 seconds (web) | ~100ms (local) |
| Accuracy | Uncertain | Authoritative (source code + docs) |
| Completeness | Partial docs | Full implementation + tests + your content |
| Rate limits | Yes | None |
The simple rule: Query BK for any question about libraries, dependencies, or reference material.
BK 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.
| Question Type | Examples |
|---|---|
| Library internals | "How does Express handle middleware errors?", "What does useEffect cleanup do?" |
| API signatures | "What parameters does axios.create() accept?", "What options can I pass to Hono?" |
| Error handling | "What errors can Zod throw?", "Why might this library return undefined?" |
| Version behavior | "What changed in React 18?", "Is this method deprecated?" |
| Configuration | "What config options exist for Vite?", "What are the defaults?" |
| Testing patterns | "How do the library authors test this?", "How should I mock this?" |
| Performance/internals | "Is this cached internally?", "What's the complexity?" |
| Security | "How does this library validate input?", "Is this safe against injection?" |
| Integration | "How do I integrate X with Y?", "What's the idiomatic way to use this?" |
| Question Type | Use Instead |
|---|---|
| Your project code | Grep/Read directly ("Where is OUR auth middleware?") |
| General concepts | Training data ("What is a closure?") |
| Breaking news | Web search ("Latest React release notes") |
"How does [library] work..." → Query BK
"What does [library function] do..." → Query BK
"What options does [library] accept..."→ Query BK
"What errors can [library] throw..." → Query BK
"Where is [thing] in OUR code..." → Grep/Read directly
"What is [general concept]..." → Training data
/bluera-knowledge:add-repo https://github.com/lodash/lodash/bluera-knowledge:add-folder ./docs --name=project-docs/bluera-knowledge:search "deep clone object"/bluera-knowledge:stores[!TIP] Not sure which libraries to index? Use
/bluera-knowledge:suggestto analyze your project's dependencies.
# Add a library
bluera-knowledge store create lodash --type repo --source https://github.com/lodash/lodash
# Index your docs
bluera-knowledge store create project-docs --type file --source ./docs
# Test search
bluera-knowledge search "deep clone object"
# View stores
bluera-knowledge store list
While bluera-knowledge indexes and searches code in any language, certain advanced features are language-specific:
| Language | Code Graph | Call Analysis | Import Tracking | Method Tracking |
|---|---|---|---|---|
| TypeScript/JavaScript | ✅ Full Support | ✅ Functions & Methods | ✅ Full | ✅ Class Methods |
| Python | ✅ Full Support | ✅ Functions & Methods | ✅ Full | ✅ Class Methods |
| Rust | ✅ Full Support | ✅ Functions & Methods | ✅ Full | ✅ Struct/Trait Methods |
| Go | ✅ Full Support | ✅ Functions & Methods | ✅ Full | ✅ Struct/Interface Methods |
| ZIL | ✅ Full Support | ✅ Routines | ✅ INSERT-FILE | ✅ Objects/Rooms |
| Other Languages | ⚠️ Basic Support | ❌ | ❌ | ❌ |
[!NOTE] 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.
Bluera 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.
What adapters provide:
Built-in adapters:
| Language | Extensions | Symbols | Imports |
|---|---|---|---|
| ZIL | .zil, .mud | ROUTINE, OBJECT, ROOM, GLOBAL, CONSTANT | INSERT-FILE |
Example - ZIL indexing:
# Index a Zork source repository
bluera-knowledge store create zork1 --type repo --source https://github.com/historicalsource/zork1
# Search for routines
bluera-knowledge search "V-LOOK routine" --stores zork1
The plugin provides AI agents with four complementary search capabilities:
AI-powered search across all indexed content
Fast keyword and pattern matching
Combines vector and FTS search
Traditional file operations on cloned sources
When you use /bluera-knowledge: commands, here's what happens:
/bluera-knowledge:stores or similar in Claude Codemcp__bluera-knowledge__* toolsExample Flow:
You: /bluera-knowledge:stores
↓
Command file instructs Claude Code to use execute("stores")
↓
MCP tool queries LanceDB for store metadata
↓
Claude Code formats results as a table
↓
You see: Beautiful table of all your knowledge stores
This architecture means commands provide a clean user interface while MCP tools handle the backend operations.
You manage knowledge stores through /bluera-knowledge: commands:
AI agents access knowledge through Model Context Protocol (3 tools for minimal context overhead):
| Tool | Purpose |
|---|---|
search | 🔍 Semantic vector search across all stores (includes store paths for direct file access) |
get_full_context | 📖 Retrieve complete code context by result ID or file path |
execute | ⚡ Meta-tool for store/job management commands |
The execute tool consolidates store and job management into a single tool with subcommands:
stores, store:info, store:create, store:index, store:delete, stores:pulljobs, job:status, job:cancelhelp, commands[!TIP] Long-running operations (git clone, indexing) run in the background, allowing you to continue working while they complete.
When you add a repository or index content:
/bluera-knowledge:check-status# Add a large repository (returns immediately with job ID)
/bluera-knowledge:add-repo https://github.com/facebook/react
# Output:
# ✓ Created store: react (a1b2c3d4...)
# 🔄 Indexing started in background
# Job ID: job_abc123def456
#
# Check status with: /bluera-knowledge:check-status job_abc123def456
# Check progress anytime
/bluera-knowledge:check-status job_abc123def456
# Output:
# Job Status: job_abc123def456
# Status: running
# Progress: ███████████░░░░░░░░░ 45%
# Message: Indexed 562/1,247 files
# View all active jobs
/bluera-knowledge:check-status
# Cancel if needed
/bluera-knowledge:cancel job_abc123def456
Background jobs include significant performance optimizations:
Provide AI agents with canonical dependency implementation details:
/bluera-knowledge:suggest
/bluera-knowledge:add-repo https://github.com/expressjs/express
# AI agents can now:
# - Semantic search: "middleware error handling"
# - Direct access: Grep/Glob through the cloned express repo
Make project-specific documentation available:
/bluera-knowledge:add-folder ./docs --name=project-docs
/bluera-knowledge:add-folder ./architecture --name=architecture
# AI agents can search across all documentation or access specific files
Provide definitive coding standards and best practices:
/bluera-knowledge:add-folder ./company-standards --name=standards
/bluera-knowledge:add-folder ./api-specs --name=api-docs
# AI agents reference actual company standards, not generic advice
Combine canonical library code with project-specific patterns:
/bluera-knowledge:add-repo https://github.com/facebook/react --name=react
/bluera-knowledge:add-folder ./docs/react-patterns --name=react-patterns
# Search across both dependency source and team patterns
Run /bluera-knowledge:doctor to diagnose common issues. This checks:
Works even when MCP is broken (uses Bash tool directly).
Ensure the plugin is installed and enabled:
/plugin list
/plugin enable bluera-knowledge
If the plugin isn't listed, install it:
/plugin marketplace add blueraai/bluera-marketplace
/plugin install bluera-knowledge@bluera
If the MCP server shows as failed after installation:
/bluera-knowledge:doctor - This diagnoses the most common issues/logs errors to see recent errors or /logs module bootstrap for startup logs/mcp to see connection status/plugin uninstall bluera-knowledge then /plugin install bluera-knowledge@blueraCommon MCP failure causes:
| Symptom | Cause | Fix |
|---|---|---|
npm ERR! ERESOLVE in logs | Peer dependency conflict | Fixed in v0.22.6+ with npm flag |
| Old plugin version running | Multiple cached versions | Fixed in v0.22.7+ (version sorting) |
make not found | Missing build tools | Install build-essential (Linux) |
| Compilation errors on Node 24 | V8 API changes | Use Node.js v20.x or v22.x |
If the issue persists, check that Claude Code is v2.0.65 or later (earlier versions had MCP loading bugs).
Check Playwright browser installation:
npx playwright install chromium
The plugin attempts to auto-install Playwright browsers on first use, but manual installation may be needed in some environments.
/bluera-knowledge:stores/bluera-knowledge:index <store-name>--stores=<name>This error occurs when a store was indexed with a different embedding model than the current configuration. As of v0.25+, stores are indexed with snowflake-arctic-embed-s (previously bge-small-en-v1.5).
Solution: Reindex the affected store:
/bluera-knowledge:index <store-name>
Check model status for all stores:
# Via MCP execute command
execute stores:check-models
This lists all stores with their embedding model and flags any that need reindexing.
List all stores to see available names and IDs:
/bluera-knowledge:stores
Use the exact store name or ID shown in the table.
tree-sitter and lancedb require native module compilation. Node.js v24 introduced V8 API changes that break these modules.
Solution: Use Node.js v20.x or v22.x (LTS versions):
# Using nvm
nvm install 22
nvm use 22
Run /bluera-knowledge:doctor to verify your environment.
Native modules require build tools:
# Debian/Ubuntu
sudo apt install build-essential
# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
Then restart Claude Code for auto-setup to complete.
Large repositories (10,000+ files) take longer to index. If indexing fails:
git --version/logs errors or /logs search "index"This means intelligent crawling is unavailable. The crawler will automatically use simple BFS mode instead.
To enable intelligent crawling with --crawl and --extract:
claude command is in PATH: which claudeSimple mode still crawls effectively—it just doesn't use AI to select which pages to crawl or extract specific content.
The plugin logs all MCP server operations to .bluera/bluera-knowledge/logs/app.log (relative to project root).
View logs using the /logs command:
/logs # Watch logs in real-time (tail -f)
/logs view 50 # View last 50 log entries
/logs errors # Show only error-level logs
/logs module mcp-store # Filter by module (mcp-server, mcp-store, mcp-execute, mcp-job, mcp-sync, bootstrap)
/logs search "pattern" # Search for a pattern
Log modules:
bootstrap - MCP server startup and dependency installationmcp-server - Core MCP server operationsmcp-store - Store create/list/delete operationsmcp-search - Search queries and resultsmcp-execute - Meta-tool command executionmcp-job - Background job statusmcp-sync - Store sync operationsManual access:
tail -f .bluera/bluera-knowledge/logs/app.log
Logs are JSON formatted (NDJSON) and can be processed with jq for pretty-printing.
Required for Web Crawling:
Optional:
Setup (automatic):
Setup runs automatically on first session start. This installs:
If you see "Setup running in background...", wait ~30s and restart Claude Code.
Manual setup (if auto-setup fails):
npx playwright install chromium
[!NOTE] 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
--fastfor static sites when speed is critical.
Update Plugin:
/plugin update bluera-knowledge
[!NOTE] 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.
Bluera Knowledge includes built-in Skills that teach Claude Code how to use the plugin effectively. Skills provide procedural knowledge that complements the MCP tools.
knowledge-searchTeaches the two approaches for accessing dependency sources:
When to use: Understanding how to query indexed libraries
when-to-queryDecision guide for when to query BK stores vs using Grep/Read on current project.
When to use: Deciding whether a question is about libraries or your project code
advanced-workflowsMulti-tool orchestration patterns for complex operations.
When to use: Progressive library exploration, adding libraries, handling large results
search-optimizationGuide on search parameters and progressive detail strategies.
When to use: Optimizing search results, choosing the right intent and detail level
store-lifecycleBest practices for creating, indexing, and managing stores.
When to use: Adding new stores, understanding when to use repo/folder/crawl
Skills teach how to use the MCP tools effectively:
This hybrid approach reduces unnecessary tool calls and context usage while maintaining universal MCP compatibility.
Example:
search(query, intent, detail, limit, stores)intent for your question type, when to use detail='minimal' vs 'full', how to narrow with storesResult: Fewer tool calls, more accurate results, less context consumed.
BK activates automatically when you work with dependencies — no manual invocation needed.
How it works:
Knowledge stores are stored in your project root:
<project-root>/.bluera/bluera-knowledge/
├── data/
│ ├── repos/<store-id>/ # Cloned Git repositories
│ ├── documents_*.lance/ # Vector indices (Lance DB)
│ └── stores.json # Store registry
├── stores.config.json # Store definitions (git-committable!)
└── config.json # Configuration
Store 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.
Example stores.config.json:
{
"version": 1,
"stores": [
{ "type": "file", "name": "my-docs", "path": "./docs" },
{ "type": "repo", "name": "react", "url": "https://github.com/facebook/react" },
{ "type": "web", "name": "api-docs", "url": "https://api.example.com/docs", "depth": 2 }
]
}
When a teammate clones the repo, they can run /bluera-knowledge:sync to recreate all stores locally.
.gitignore PatternsWhen you first create a store, the plugin automatically updates your .gitignore with:
# Bluera Knowledge - data directory (not committed)
.bluera/
!.bluera/bluera-knowledge/
!.bluera/bluera-knowledge/stores.config.json
This ensures:
| Document | Description |
|---|---|
| CLI Reference | Complete CLI commands, options, and usage examples |
| MCP Integration | MCP server configuration and tool documentation |
| Commands Reference | All slash commands with parameters and examples |
| Crawler Architecture | How the intelligent web crawler works |
| Token Efficiency | How BK reduces token consumption vs web search |
| CONTRIBUTING | Development setup, testing, and release process |
Contributions welcome! See CONTRIBUTING.md for development setup, testing, and release process.
MIT - See LICENSE for details.
This project includes software developed by third parties. See NOTICE for full attribution.
Key dependencies:
FAQs
CLI tool for managing knowledge stores with semantic search
The npm package bluera-knowledge receives a total of 461 weekly downloads. As such, bluera-knowledge popularity was classified as not popular.
We found that bluera-knowledge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.