llmdex

Local semantic search for your projects. No API keys, no cloud — everything runs on your machine.

"How does auth work?"

	Without llmdex	With llmdex
Time	~2 min	~20 sec
Cost (implementation task)	~$1.20	~$0.50
Cost (explanation task)	~$0.25	~$0.10

Real benchmarks with Claude Code on a production codebase.

llmdex indexes your project files (Markdown, TypeScript, JSON) into a local vector database and lets you search by meaning, not just keywords.

Inspired by the original idea and Python scripts of @lnetrebskii.

Install

# uv (recommended)
uv tool install git+https://github.com/anetrebskii/llmdex

# or pipx
pipx install git+https://github.com/anetrebskii/llmdex

# pin a specific version
uv tool install git+https://github.com/anetrebskii/[email protected]

Requires Python 3.10+.

Quick start

# 1. Index your project
cd ~/my-project
llmdex index

# 2. Search
llmdex query "how does authentication work"

That's it. The first query takes ~25s (model loading), all subsequent queries are instant.

Using with Claude Code

# Add llmdex instructions to Claude Code (global — works in every project)
llmdex init global

# Or per-project only
llmdex init

This teaches Claude Code to use llmdex for semantic search automatically. See Claude Code integration for details.

Commands

llmdex index — Build the index

# Index current directory
llmdex index

# Index a specific project
llmdex index /path/to/project

# Index specific file types
llmdex index /path/to/project -e .md .ts .py .json

# Assign tags while indexing (repeatable)
llmdex index /path/to/project -t project:foo -t type:code

# Split mode: also index each immediate subfolder as a separate child
# index, tagged folder:<name>. Lets you narrow queries to one subfolder.
llmdex index /path/to/project --split

Split indexing (--split)

For large directories (monorepos, doc sites) where one monolithic index returns noisy results. --split creates a root index plus a separate child index per immediate subfolder (depth 1). Each child inherits the parent's tags and gets an automatic folder:<name> tag so you can narrow queries to one subfolder:

llmdex index ~/docs --split -t project:docs

# Query everything under docs
llmdex query -t project:docs "authentication"

# Query only the api/ subfolder
llmdex query -t project:docs -t folder:api "authentication"

Behavior:

• Root index only contains files at the top level (no subfolder files — avoids duplication).
• Subfolders in SKIP_DIRS (node_modules, .git, dist, ...) are skipped.
• Subfolders with no matching files are skipped (no empty indexes).
• llmdex reindex on a split parent automatically re-splits and picks up new/removed subfolders.
• llmdex remove on a split parent cascades and removes all children + their storage.

llmdex add — Register a project without indexing

Registers a directory (with extensions and optional tags) so a later llmdex reindex will build its index. Useful for scripting bulk setup.

llmdex add /path/to/project -e .md .ts -t project:foo

llmdex reindex — Re-index all registered projects

Rebuilds indexes for all previously registered projects. Uses the file extensions stored during the original llmdex index call.

llmdex reindex

# Force a full rebuild (ignore change detection)
llmdex reindex -f

Skips directories that no longer exist on disk. Split parents automatically re-split their children.

llmdex list — List all indexed projects

llmdex list

llmdex remove — Remove a project from the registry

llmdex remove /path/to/project

Indexes are stored centrally in ~/.llmdex/indexes/ — project directories stay clean.

What gets indexed by default:

• .md files — parsed by headings and sections
• .ts files — parsed by code structure (functions, classes)
• .json files — parsed by text chunks

What gets skipped:
node_modules, .git, dist, build, .next, .venv, __pycache__, and other common build/cache directories.

llmdex query — Search the index

# Basic search
llmdex query "database connection setup"

# Search a specific project
llmdex query -d /path/to/project "error handling"

# Search across all indexed projects
llmdex query -a "API endpoints"

# Get more results (default: 10)
llmdex query -k 20 "API endpoints"

# Filter results to files under a folder prefix
llmdex query -f src/api "error handling"

# Compact output: file:lines only, no preview (for chaining / AI tools)
llmdex query -c "auth flow"

Output:

Query: database connection setup
Top 5 results:

1. [0.742] /Users/you/my-project/src/db/connection.ts
   export async function connectDatabase(config: DbConfig) { const pool = new Pool({...

2. [0.698] /Users/you/my-project/docs/setup.md
   ## Database Configuration  Set the following environment variables...

Each result shows a relevance score (0-1), the full file path, and a text preview.

You can also filter queries by tag (see below):

# Search only indexes tagged "backend"
llmdex query -t backend "database connection"

# Combine tags (AND logic — matches indexes with ALL specified tags)
llmdex query -t backend -t api "error handling"

llmdex tag — Set tags on an indexed project

Tags let you organize indexes and filter queries across multiple projects.

# Set tags on the current directory
llmdex tag . backend api

# Set tags on a specific project
llmdex tag /path/to/project frontend react

# Show current tags for a project
llmdex tag /path/to/project

Tags replace any previously set tags (they are not additive).

llmdex describe — Set or show an index description

Attach a human-readable description to an indexed folder. Descriptions show up in llmdex catalog and help Claude (or you) pick the right index for a given question.

# Set a description
llmdex describe /path/to/project Meeting notes and retros for the twinsai team

# Show current description
llmdex describe /path/to/project

You can also pass -D / --description when indexing or adding:

llmdex index . -t project:twinsai -D "Engineering docs and ADRs"
llmdex add .  -t project:twinsai -D "Engineering docs and ADRs"

llmdex catalog — List all indexed projects with tags and descriptions

Use this for discovery: it shows every indexed folder together with its tags and description, so you can decide which index to query.

llmdex catalog

Output:

/Users/you/twinsai
  tags: project:twinsai, type:docs
  description: Weekly syncs, retros, and ADRs
  subfolders (2):
    /Users/you/twinsai/meetings  [folder:meetings]
      description: Raw meeting notes
    /Users/you/twinsai/adrs  [folder:adrs]

llmdex tags — List all tags

Shows all tags and which indexed directories have each tag.

llmdex tags

Output:

  backend
    /Users/you/api-service
    /Users/you/worker

  frontend
    /Users/you/web-app

llmdex server — Manage the background server

The query server starts automatically on first llmdex query call. It keeps the embedding model in memory so subsequent queries are fast.

# Start manually
llmdex server

# Custom port (default: 7392)
llmdex server -p 8080

# Custom inactivity timeout in seconds (default: 1800 = 30 min)
llmdex server -t 3600

# Stop the server
llmdex server --stop

# Restart the server
llmdex server --restart

The server shuts down automatically after 30 minutes of inactivity. After a package update, the server automatically restarts on the next command when it detects a version mismatch.

Server HTTP API

The server exposes a local HTTP API on 127.0.0.1:7392. You can use it directly with curl:

# Index a project
curl -s http://127.0.0.1:7392/index \
  -H "Content-Type: application/json" \
  -d '{"directory": "/path/to/project", "extensions": [".md", ".ts", ".py"]}'

# Search
curl -s http://127.0.0.1:7392/query \
  -H "Content-Type: application/json" \
  -d '{"directory": "/path/to/project", "question": "auth flow", "top_k": 5}'

# Reload index after re-indexing
curl -s http://127.0.0.1:7392/invalidate \
  -H "Content-Type: application/json" \
  -d '{"directory": "/path/to/project"}'

# Health check
curl http://127.0.0.1:7392/health

How it works

1. Indexing — Files are parsed into chunks using smart parsers (Markdown by headings, TypeScript by code structure, JSON by text boundaries). Each chunk is embedded into a vector using all-MiniLM-L6-v2, a small local model (~80MB). Vectors are stored in ~/.llmdex/indexes/.

2. Querying — Your search query is embedded with the same model, then compared against all stored vectors to find the most semantically similar chunks. This means "how does login work" will find code about authentication even if the word "login" doesn't appear.

3. Server — A lightweight HTTP server keeps the embedding model and indexes in memory between queries. It auto-starts on first query and auto-stops after 30 minutes of inactivity. You can also stop it manually with llmdex server --stop.

Typical workflow

# First time: index the project
cd ~/my-project
llmdex index

# Search anytime
llmdex query "payment processing"
llmdex query "how are emails sent"
llmdex query -k 10 "error handling in API routes"

# After major code changes: re-index
llmdex index

Claude Code integration

llmdex init — Integrate with Claude Code

Adds a ## LLMDEX — Semantic Search section to CLAUDE.md that teaches Claude Code when and how to use llmdex for semantic search.

# Add to the current project's .claude/CLAUDE.md (default)
llmdex init

# Add globally to ~/.claude/CLAUDE.md — works in every project
llmdex init global

Cost optimization: llmdex reduces Claude Code API costs by 50-60% on typical tasks. Instead of scanning dozens of files to find relevant code, Claude gets precise results from llmdex and spends tokens on the actual work. The savings scale with codebase size -- larger projects see bigger gains.

• Project scope (default) — instructions are tailored for single-project use
• Global scope — instructions include cross-project features (tags, -a flag)
• Running it again is safe — it detects the existing section and won't duplicate it
• Creates .claude/ directory and CLAUDE.md if they don't exist

Updating

# uv
uv tool install --force git+https://github.com/anetrebskii/llmdex

# pipx
pipx install --force git+https://github.com/anetrebskii/llmdex

Uninstall

# uv
uv tool uninstall llmdex

# pipx
pipx uninstall llmdex

# Remove all data (indexes + server PID)
rm -rf ~/.llmdex

License

MIT