BearWisdom

Structural code intelligence that's un-bear-ably fast.
31 languages. Cross-framework graph. Hybrid search. One index.

Features · Quick Start · Web Explorer · CLI Reference · Architecture · MCP Server

What Is This?

BearWisdom is a code intelligence engine that builds a structural understanding of your entire codebase — symbols, edges, call hierarchies, concepts, and cross-language flows — and makes it searchable in milliseconds.

It parses your code with tree-sitter, stores everything in a local SQLite graph database, and exposes the results through a CLI, MCP server, web UI, and Claude Code agent. Think of it as a bear that hibernated with your codebase and woke up knowing where everything is.

Why "BearWisdom"? Because understanding code shouldn't require grizzly effort. Let the bear do the heavy lifting.

Features

The Bear Necessities

31 languages — C#, TypeScript, JavaScript, Python, Rust, Go, Java, C/C++, Ruby, PHP, Kotlin, Swift, Scala, Haskell, Elixir, Dart, Lua, R, HTML, CSS, JSON, YAML, Bash, SQL, Markdown, XML, Dockerfile, and more
Structural graph — symbols, edges (calls, inherits, implements, type_ref, instantiates), concepts, and annotations stored in SQLite
5-priority resolver — namespace imports, scope analysis, qualified name matching, file-path correlation, and kind-based inference
Cross-framework connectors — Spring Boot, Django, .NET DI, EF Core, gRPC, GraphQL, Electron IPC, Tauri IPC, React/Zustand, and HTTP API routes

Search That's Barely Believable

FTS5 symbol search — BM25-ranked full-text search across all symbol names and qualified names
Fuzzy finder — nucleo-powered fuzzy matching for files (Ctrl+P) and symbols (Ctrl+T)
Content search — FTS5 trigram index for substring search across file content
Grep — gitignore-aware regex/literal search with scope filtering
Hybrid search — FTS5 + ONNX vector embeddings fused via Reciprocal Rank Fusion
Semantic search — natural language queries via CodeRankEmbed embeddings

Analysis That's Polar-izing

Architecture overview — language breakdown, hotspot detection, entry point discovery
Blast radius — "if I change X, what breaks?" via recursive CTE graph traversal
Call hierarchy — incoming and outgoing call chains with edge provenance
Concept discovery — automatic namespace grouping with member assignment
Subgraph export — filtered graph export for D3/Cytoscape visualization

Ways to Interact

Interface	Description
`bw` CLI	25 JSON-output commands for scripts and agents
Web Explorer	React + D3 force-directed knowledge graph with search
MCP Server	Model Context Protocol server for Claude and other LLMs
Claude Code Agent	Conversational subagent that wraps the CLI

Quick Start

Prerequisites

Rust 1.75+ (edition 2021)
Node.js 18+ (for the web explorer, optional)
ONNX Runtime (required for AI search / semantic embeddings)
- Install via Python: pip install onnxruntime and set ORT_DYLIB_PATH to the onnxruntime shared library inside that package, or download a standalone release from github.com/microsoft/onnxruntime/releases and point ORT_DYLIB_PATH at onnxruntime.dll / libonnxruntime.so / libonnxruntime.dylib
- Without ORT_DYLIB_PATH the engine starts normally but bw hybrid, bw embed, and AI Search in the web UI will return an error

Build

# Clone the repo
git clone https://github.com/MariusAlbu/BearWisdom.git
cd BearWisdom

# Build all crates
cargo build --release

# The CLI binary is at:
./target/release/bw --help

Index a Project

# Full index with concept discovery + automatic embedding (if ORT_DYLIB_PATH is set)
bw open /path/to/your/project

# Check index stats
bw status /path/to/your/project

The index is stored at <project>/.bearwisdom/index.db — a single SQLite file. Add .bearwisdom/ to your project's .gitignore.

For AI search, bw open automatically computes CodeRankEmbed embeddings after indexing when ORT_DYLIB_PATH is set. You can also run embedding standalone:

# Download the CodeRankEmbed model first (one time)
# Place it at <project>/models/CodeRankEmbed  OR  ~/.bearwisdom/models/CodeRankEmbed

# Compute embeddings independently
bw embed /path/to/your/project

# Run LSP enrichment independently
bw enrich /path/to/your/project

Search

# Find symbols by name
bw search-symbols /path/to/project "ProductService"

# Fuzzy find files (like Ctrl+P)
bw fuzzy-files /path/to/project "ProdServ"

# Fuzzy find symbols (like Ctrl+T) — yes, it's *fuzzy*, like a bear
bw fuzzy-symbols /path/to/project "GetById"

# Grep across files
bw grep /path/to/project "TODO" --case-insensitive

# Content search (trigram, min 3 chars)
bw search-content /path/to/project "repository"

# Hybrid search (FTS + embeddings when model is available)
bw hybrid /path/to/project "authentication middleware"

Navigate

# Go to definition
bw definition /path/to/project "ProductService"

# Find all references
bw references /path/to/project "IProductRepository"

# List symbols in a file
bw file-symbols /path/to/project "Services/ProductService.cs"

# Full symbol detail
bw symbol-info /path/to/project "ProductService"

Analyze

# Architecture overview
bw architecture /path/to/project

# Blast radius — what breaks if I change this?
bw blast-radius /path/to/project "Product" --depth 3

# Who calls this?
bw calls-in /path/to/project "GetById"

# What does this call?
bw calls-out /path/to/project "PlaceOrder"

# Cross-language flow trace
bw trace-flow /path/to/project "Controllers/OrderController.cs" 45

Concepts

# Discover namespace concepts automatically
bw discover-concepts /path/to/project

# List concepts
bw concepts /path/to/project

# Show concept members
bw concept-members /path/to/project "MyApp.Services"

# Export graph filtered by concept
bw export-graph /path/to/project --filter "@MyApp.Services"

Web Explorer

BearWisdom includes a web-based knowledge graph explorer. It's a React + D3 application that lets you visually explore the structural graph.

Run

# Build the frontend (one time)
cd web && npm install && npm run build && cd ..

# Start the server
cargo run -p bearwisdom-web --release -- --static-dir web/dist

# Open http://localhost:3030

What You Can Do

Browse your filesystem and select a project to index
Explore the force-directed knowledge graph — drag, zoom, pan, hover to highlight connections
Filter by concept — click a concept in the sidebar to isolate that subgraph
Search 6 ways — Symbols, Fuzzy, Files, Content, Grep, and AI Search tabs
Enable AI Search — the web UI has an "Enable AI Search" button that triggers embedding computation on demand (requires ORT_DYLIB_PATH set in the server environment)
Inspect symbols — click a node to see its signature, documentation, incoming/outgoing calls
View source — file/content/grep results open a full code viewer with line highlighting
Resize the detail panel — drag the left edge to make room for code review

Development

# Backend (auto-rebuilds on change)
cargo run -p bearwisdom-web -- --port 3030

# Frontend dev server (hot reload, proxies /api to :3030)
cd web && npm run dev
# Open http://localhost:5173

CLI Reference

All commands output JSON to stdout. Envelope: {"ok": true, "data": {...}} or {"ok": false, "error": "..."}.

Command	Description
`bw open <path>`	Full index + concept discovery + post-index embedding
`bw status <path>`	Index stats (read-only)
`bw embed <path>`	Compute CodeRankEmbed embeddings standalone
`bw enrich <path>`	Run LSP enrichment standalone
`bw architecture <path>`	Language stats, hotspots, entry points
`bw search-symbols <path> <query>`	FTS5 symbol search
`bw fuzzy-files <path> <pattern>`	Fuzzy file finder
`bw fuzzy-symbols <path> <pattern>`	Fuzzy symbol finder
`bw search-content <path> <query>`	FTS5 trigram content search
`bw grep <path> <pattern>`	Regex/literal grep
`bw hybrid <path> <query>`	Hybrid FTS + vector search
`bw definition <path> <symbol>`	Go to definition
`bw references <path> <symbol>`	Find all references
`bw file-symbols <path> <file>`	Symbols in a file
`bw symbol-info <path> <symbol>`	Full symbol detail
`bw blast-radius <path> <symbol>`	Impact analysis
`bw calls-in <path> <symbol>`	Incoming call hierarchy
`bw calls-out <path> <symbol>`	Outgoing call hierarchy
`bw trace-flow <path> <file> <line>`	Cross-language flow
`bw concepts <path>`	List concepts
`bw discover-concepts <path>`	Auto-discover concepts
`bw concept-members <path> <concept>`	Concept members
`bw export-graph <path>`	Graph export (JSON)

Architecture

See the Architecture Diagram for a visual overview.

bearwisdom/                    Core library — parser, indexer, query, search, bridge
  src/
    parser/                    Tree-sitter extractors (31 languages)
    indexer/                   Full + incremental indexing
    query/                     Architecture, blast radius, call hierarchy, concepts, search
    search/                    Grep, FTS5, fuzzy, hybrid, embeddings, vector store
    bridge/                    LSP integration, SCIP import, background enrichment
    connectors/                Cross-framework edge detection (Spring, Django, EF Core, etc.)
    db/                        SQLite schema, database management

bearwisdom-cli/                CLI binary (bw) — 25 JSON commands
bearwisdom-mcp/                MCP server (bw-mcp) — tool registration
bearwisdom-web/                Web server (bw-web) — Axum HTTP + static files
bearwisdom-profile/            Language detection, project scanning
bearwisdom-bench/              Benchmark harness

web/                           React + D3 frontend (Vite + TypeScript)
tests/                         Integration test suite
agents/                        Claude Code agent definitions

Bundled Dependencies

sqlite-vec is statically linked into the BearWisdom binary. No SQLITE_VEC_PATH environment variable or external .dll/.so is needed — vector search works out of the box.

ONNX Runtime is loaded dynamically at runtime via the load-dynamic feature. Set ORT_DYLIB_PATH to the path of the shared library before running any embedding command. sqlite-vec handles storage; ONNX Runtime handles inference.

Database Schema

The SQLite database stores:

Table	Purpose
`files`	Indexed files with path, language, content hash, and timestamp
`symbols`	Extracted symbols (name, qualified_name, kind, line, signature, doc_comment)
`edges`	Directed relationships (calls, inherits, implements, type_ref, instantiates) with confidence
`unresolved_refs`	References pending LSP/SCIP resolution
`imports`	Import/using directives per file, used by the 5-priority resolver
`routes`	HTTP route endpoints extracted by framework connectors
`db_mappings`	EF Core entity-to-table mappings
`symbols_fts`	FTS5 virtual table for BM25-ranked symbol search
`annotations`	Free-form markdown notes attached to symbols
`concepts`	Namespace groupings with auto_pattern for membership matching
`concept_members`	Symbol-to-concept assignments (manual and auto)
`lsp_edge_meta`	LSP-resolved edge provenance
`fts_content`	FTS5 trigram virtual table for file content search
`code_chunks`	AST-aware chunks aligned to symbol boundaries, used for embeddings
`flow_edges`	Cross-language flow edges (TS→C#, gRPC client→server, etc.)
`search_history`	Recent and saved searches with query type and scope

MCP Server

BearWisdom ships an MCP (Model Context Protocol) server that exposes all capabilities as tools for Claude Code and other LLM agents. The server indexes the project in the background on startup and makes all query tools available immediately.

Setup

# Build the MCP server (release recommended — it runs as a long-lived process)
cargo build --release -p bearwisdom-mcp

# Register it for a specific project
./target/release/bw-mcp register --project /path/to/your/project

This writes a bearwisdom entry into <project>/.mcp.json. Next time you open Claude Code in that project directory, the MCP server starts automatically.

Manual usage

# Run standalone (indexes current directory by default)
./target/release/bw-mcp

# Run for a specific project
./target/release/bw-mcp --project /path/to/your/project

# Unregister from a project
./target/release/bw-mcp unregister --project /path/to/your/project

The server communicates over stdio using JSON-RPC (MCP protocol). On startup it runs a full index in the background — tool calls during indexing will block briefly until the current batch finishes.

Claude Code Agent

The agents/bearwisdom.md agent lets you interrogate any codebase conversationally:

> /bearwisdom

You: What's the architecture of this project?
Bear: Running bw architecture... [shows language stats, hotspots, entry points]

You: Who calls ProductService?
Bear: Running bw calls-in ProductService... [shows call hierarchy]

You: What would break if I change the Order model?
Bear: Running bw blast-radius Order --depth 3... [shows impact analysis]

Project Structure

Crate	Type	Description
`bearwisdom`	lib	Core engine — 31-language parser, graph DB, hybrid search
`bearwisdom-cli`	bin (`bw`)	CLI with 25 JSON commands
`bearwisdom-mcp`	bin (`bw-mcp`)	MCP server for LLM agents
`bearwisdom-web`	bin (`bw-web`)	Axum HTTP server + React UI
`bearwisdom-profile`	lib	Language detection, project scanning
`bearwisdom-bench`	bin	Performance benchmarks

License

MIT License. See LICENSE-MIT for details.

Built with the patience of a bear and the precision of tree-sitter.
May your searches always be fuzzy in the right way. 🐻

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
agents		agents
assets		assets
benchmarks		benchmarks
crates		crates
docs		docs
scripts		scripts
tests		tests
web		web
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-MIT		LICENSE-MIT
README.md		README.md
SECURITY.md		SECURITY.md
clippy.toml		clippy.toml
rustfmt.toml		rustfmt.toml

Folders and files

Latest commit

History

Repository files navigation

BearWisdom

What Is This?

Features

The Bear Necessities

Search That's Barely Believable

Analysis That's Polar-izing

Ways to Interact

Quick Start

Prerequisites

Build

Index a Project

Search

Navigate

Analyze

Concepts

Web Explorer

Run

What You Can Do

Development

CLI Reference

Architecture

Bundled Dependencies

Database Schema

MCP Server

Setup

Manual usage

Claude Code Agent

Project Structure

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages