README

# delphi-lookup - Fast Pascal Code Search for AI Agents

High-performance source code search and navigation system for Pascal codebases, designed for AI coding agents like Claude Code.

Includes an LSP server that gives Claude Code native go-to-definition, hover, find-references, and document-symbols on .pas files — the same navigation experience you get in an IDE, but for AI agents.

Features

• LSP Server - Native Claude Code integration: go-to-definition, hover, references, document symbols on .pas files
• Fast CLI Search - ~75ms end-to-end for identifier lookups (short-circuit on exact match), ~75ms cached
• Smart Search - 3-phase cascade: exact NOCASE → prefix → substring, then FTS5 + fuzzy
• Declaration Priority - Declarations rank above implementations with [Decl] badges
• Smart Caching - Content-hash based cache that survives reindexing
• Incremental Indexing - Merkle-style change detection; no-change verification in <10ms
• Parallel Processing - Multi-threaded AST parsing and folder scanning
• Category Filtering - Separate user code, stdlib, third-party
• Framework Detection - Multi-tier VCL/FMX/RTL classification (packages, uses clause, path)
• Scalable - Tested with 672K+ symbols (3.2GB database)

Claude Code LSP Server

The LSP server gives Claude Code native IDE-like navigation on Pascal files — no prompts or skills needed, it just works as a tool:

LSP goToDefinition  ???  Jump to where TMyClass is defined
LSP hover           ???  See the full class declaration with docs
LSP documentSymbol  ???  Get a structured outline of any .pas file
LSP findReferences  ???  Find all files that reference a symbol

Note: workspaceSymbol is not functional — Claude Code sends an empty query string (#17149). Use delphi-lookup.exe for workspace-wide symbol search.

Setup: Install the plugin and point it to your indexed database. See claude-code/SETUP.md for step-by-step instructions (Windows and WSL).

Quick Start

Installation

1. Download the latest release or build from source
2. Ensure sqlite3.dll is in the bin/ folder (included)

Basic Usage

# 1. Build index from your Pascal source
delphi-indexer.exe "C:\Projects\MyDelphiApp\src" --category user

# 2. Search code
delphi-lookup.exe "TStringList" -n 5

# 3. List indexed folders
delphi-indexer.exe --list-folders

Documentation

For using the tools:

• USER-GUIDE.md - Complete usage guide, all options, examples
• CLAUDE.md - AI agent reference (configuration, architecture, code patterns)

For maintaining/extending:

• TECHNICAL-GUIDE.md - Architecture, troubleshooting, extending
• DATABASE-SCHEMA.md - Database schema reference
• QUERY-ANALYTICS.md - SQL queries for usage analysis
• TESTS.md - Testing guide and test suite
• CHANGELOG.md - Version history

Architecture

Pascal Source Files ??? delphi-indexer ??? SQLite Database (FTS5)
                                                 ???
                                    ???????????? delphi-lookup ????????? CLI Results
                                    ???????????? delphi-lsp-server ????????? Claude Code LSP

Components:

• delphi-indexer - Indexes Pascal code with AST parsing (parallel, incremental)
• delphi-lookup - Fast identifier lookup with short-circuit + hybrid search (fuzzy + FTS5) with caching
• delphi-lsp-server - Language Server Protocol server for Claude Code (definition, hover, references, symbols)
• Database - SQLite with WAL mode, FTS5 full-text search, optional vector embeddings

System Requirements

Platform: Windows x64

Runtime Dependencies:

• sqlite3.dll (FTS5-enabled, included)
• vec0.dll (sqlite-vec extension, included)

Note: Vector embedding support (via Ollama) is included but not recommended for AI agent workflows. FTS5-only is the default and recommended mode — agents iterate fast and achieve similar quality with multiple searches while being 17x faster. See CLAUDE.md for details.

Compilation Dependencies (Delphi):

• mORMot 2
• FireDAC (included with RAD Studio)
• DelphiAST (included)

Performance

End-to-end wall-clock time (exe startup + DB connection + search + formatting):

Exe startup overhead is ~65ms (process creation + DB connection + FTS5 detection). 83% of production queries are single-word Pascal identifiers that hit the short-circuit path.

Scalability: Tested with 672K+ symbols, 3.2GB database

Examples

# Basic usage
delphi-lookup.exe "TStringList" -n 5

# Search user code only
delphi-lookup.exe "TCustomForm" --category user

# Boost user code in results
delphi-lookup.exe "TForm" --prefer user -n 10

# Filter by framework
delphi-lookup.exe "TButton" --framework VCL -n 5

# Full-text search
delphi-lookup.exe "JSON serialization" -n 5

# Find constants
delphi-lookup.exe "MAX_BUFFER" --symbol const

# Indexing
delphi-indexer.exe "C:\Projects\MyLib" --category user
delphi-indexer.exe "C:\Projects\MyLib" --force        # Full reindex
delphi-indexer.exe --list-folders                      # Show indexed folders

Output Format

Compact format optimized for AI agent context windows (2-3 lines per result):

// Context for query: "CrearQuery"

Found 5 result(s) for "CrearQuery":

1. [Decl] function CrearQuery(const pSQL:string='';const pPrepare:boolean=false):TQueryMAX; overload;
   ??? TableMax.Query.pas [unit: TableMax.Query] (user, RTL)

2. [Decl] function CrearQuery(const pQuery:string): TDataset; virtual; abstract;
   ??? gmcSincronizarSQL.Tipos.Origen.pas [unit: gmcSincronizarSQL.Tipos.Origen] (user, RTL)

// Search completed in 12 ms

Declarations are tagged with [Decl]. Use --full for verbose output with code snippets.

Configuration

delphi-lookup can be configured via JSON file, environment variables, or command-line parameters.

Configuration File (recommended)

Copy delphi-lookup.example.json to delphi-lookup.json and customize:

{
  "database": "delphi_symbols.db",
  "category": "user",
  "num_results": 5
}

Key settings:

• database: SQLite database file path
• category: Default source category for indexing
• num_results: Default number of search results
• Command-line parameters override config file settings

See CLAUDE.md for full configuration reference.

AI Tool Integration

• Claude Code — LSP plugin + skill. See claude-code/SETUP.md
• Gemini CLI — One-shot configuration prompt. See gemini/GEMINI_SETUP.md

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Security

For security considerations and vulnerability reporting, see SECURITY.md.

Support

For AI Coding Agents:

• See USER-GUIDE.md for complete usage instructions
• See TECHNICAL-GUIDE.md for troubleshooting

For developers:

• Check TESTS.md for test suite
• See DATABASE-SCHEMA.md for schema details

License

This project is licensed under the MIT License - see LICENSE for details.

Third-party licenses are documented in THIRD-PARTY-LICENSES.md.

Version: 1.5.0 (2026-03-13) Target: AI Coding Agents (Claude Code, Cursor, etc.) Platform: Windows x64