Lynx transforms developer intent into stable repository coordinates — symbols, files, and structural chunks — enabling downstream reasoning systems like Lea to operate on deterministic code primitives instead of fragile text spans.
Lynx discovers. Lea reasons.
Features • Ecosystem & Architecture • Design Principles • Installation • CLI Usage • MCP Server • Repository Layout • Contributing
- Symbol-first discovery with stable, deterministic identifiers rather than fragile text snippets.
- Multilingual Support: Tree-sitter parsing for structured symbol extraction and syntax-aware chunking:
- Rust (
.rs) - Go (
.go) - TypeScript / TSX (
.ts,.tsx) - JavaScript / JSX (
.js,.jsx) - Python (
.py)
- Rust (
- Hybrid Retrieval: Integrates BM25 lexical search (via Tantivy) with semantic vector search (via FastEmbed utilizing
bge-small-en-v1.5) using Reciprocal Rank Fusion (RRF) for optimal relevance. - Local-first, CPU-first: Zero cloud or GPU dependencies. Operates entirely offline with high-performance local indexing.
- Heuristic Signal Boosting:
- Definition Boost: Prioritizes symbol definitions over code references (1.5x score multiplier).
- Noise Suppression: Filters and penalizes mock, test, generated, and vendor code automatically.
- Integrations: Supports a minimal stdio Model Context Protocol (MCP) server and integrates natively with the Lea reasoning layer.
Lynx sits at the absolute beginning of the AI-native developer pipeline. It converts human queries or vague agent intents into exact coordinates in a repository, passing them off to reasoning engines like Lea for structural analysis.
graph TD
Query[Human Request / Agent Query]
Sub1[BM25 Search]
Sub2[Vector Embeddings Search]
RRF[Reciprocal Rank Fusion]
Heuristics[Heuristic Boosting / Definition & Noise Filters]
Coordinates[Precise Symbol Coordinates]
Lea[Lea Reasoning Engine]
Agent[Downstream Developer Agent]
Query --> |Classify & Tokenize| Sub1
Query --> |Generate Embedding| Sub2
Sub1 --> RRF
Sub2 --> RRF
RRF --> Heuristics
Heuristics --> Coordinates
Coordinates --> |Deterministic Symbol IDs| Lea
Lea --> |Structural Analysis / Impact Radius| Agent
- Discovery Only: Lynx does not perform reasoning, dependency analyses, or calculate impact radius. Its sole job is to answer: "Where is this concept located?"
- Speed First: Cold queries execute in
< 100ms, while cached or warm queries resolve in< 10ms. - Token Efficiency: Instead of dumping thousands of raw lines or dozens of files, Lynx provides the minimal, precise coordinates (symbol ranges, file coordinates) needed.
- Deterministic Base: Bypasses ranking completely for exact symbol lookups (
O(1)complexity) to guarantee repeatability.
Install the CLI directly from crates.io:
cargo install pizen-lynxThe CLI installs under the binary name lx.
Configure storage paths globally using the -s or --storage-path flag (defaults to .lynx in the current project root).
Generate the semantic and symbol index for the repository:
lx index /path/to/repoNote: Test, mock, and generated files are skipped by default. To include them, pass the --include-tests flag:
lx index /path/to/repo --include-testsSearch your indexed codebase using lexical and semantic hybrid querying:
lx search "jwt validation token"Include test and generated code in search results:
lx search "jwt validation token" --include-testsResolve an exact symbol's coordinates bypassing rank-fusion:
lx resolve LoginFind related implementations and references close to a specific line:
lx related internal/auth/service.go:42Query a conceptual flow and visualize its downstream control path by triggering Lea automatically:
lx flow "user validation handler"Change the default directory for index and caching files:
lx --storage-path /tmp/lynx index .Lynx includes a built-in Model Context Protocol (MCP) server communicating over standard input/output (stdio). This allows LLMs and AI agents (like Claude Desktop) to discover files and symbols natively.
You can launch the server directly from the CLI:
lx mcpOr run the workspace binary directly:
cargo run -p lynx-mcp -- .lynxHybrid natural-language and keyword search across chunks.
- Arguments:
query(string) - JSON-RPC payload:
{"jsonrpc":"2.0", "id": 1, "method": "search", "params": {"query": "authentication flow"}}
Instant coordinate resolution for an exact symbol name.
- Arguments:
name(string) - JSON-RPC payload:
{"jsonrpc":"2.0", "id": 2, "method": "resolve_symbol", "params": {"name": "Login"}}
Retrieves implementation chunks matching or close to a coordinate.
- Arguments:
file(string),line(number) - JSON-RPC payload:
{"jsonrpc":"2.0", "id": 3, "method": "find_related", "params": {"file": "internal/auth/service.go", "line": 42}}
crates/
lynx-cli/ # CLI tool and subcommand handler (crate: pizen-lynx)
lynx-common/ # Shared utilities and core workspace structures (crate: pizen-lynx-common)
lynx-core/ # RRF pipeline, classification, indexing, and ranking (crate: pizen-lynx-core)
lynx-embed/ # Embedding abstraction and local FastEmbed provider (crate: pizen-lynx-embed)
lynx-mcp/ # Standalone MCP server over stdio (crate: pizen-lynx-mcp)
lynx-parser/ # Syntax parsing and Tree-sitter symbol extraction (crate: pizen-lynx-parser)
lynx-protocol/ # Shared serializable serialization protocols (crate: pizen-lynx-protocol)
lynx-storage/ # Tantivy lexical indexing & embedding persistence (crate: pizen-lynx-storage)
We welcome issues and pull requests! Ensure all formatters, lints, and tests pass successfully before submitting changes:
make ciMIT