slopdex

Search functions by meaning, find duplicate-code candidates, and locate related functions spread across a codebase.

Start here

Requires an embedding-provider API key. Install, set your key, and run commands from the repository you want to analyze (or pass --root /path/to/repo):

Coding agents should start with the bundled Slopdex agent skill.

npm install -g @ninjaxtools/slopdex
export OPENAI_API_KEY="your-api-key"
slopdex search "validate an authenticated session" --format summary --limit 10

The first command creates the index automatically. Later commands refresh it before searching.

Add .slopdex/ to your repository's .gitignore.

Search code

slopdex search "keep the repository index synchronized" --format summary --limit 10

Optionally enable a hosted second-stage reranker for search and search-description:

export COHERE_API_KEY="your-api-key"
slopdex config reranker cohere
# Or: export JINA_API_KEY="your-api-key" && slopdex config reranker jina
# Or use an LLM: export OPENAI_API_KEY="your-api-key" && slopdex config reranker openai

The config command is the only CLI switch for reranking. Use slopdex config reranker disable to return to embedding-only ordering. An optional final argument selects a model, for example slopdex config reranker cohere rerank-v4.0-fast. OpenAI LLM reranking defaults to gpt-5.6-luna with high reasoning and receives the top 10 embedding results; change the pool with --reranker-candidates, for example slopdex config reranker openai gpt-5.6-luna --reranker-candidates 20.

To search generated descriptions of each function's role instead:

slopdex descriptions enable
slopdex search-description "keep the repository index synchronized" --format summary --limit 10

The default description provider requires OPENAI_API_KEY even when Jina supplies embeddings. OpenCode Zen and Go use OPENCODE_API_KEY. Description generation can add provider costs; see descriptions and scoring.

descriptions disable turns off description generation while retaining cached data.

To choose from OpenCode's current published models and persist description settings without creating an index:

slopdex models opencode-go
slopdex config model opencode-go/gpt-5.6-luna
slopdex config descriptions enable

The next index-using command creates or refreshes the index and applies the configured description state. You can also pass the selection separately as slopdex config model --description-provider opencode-go --description-model gpt-5.6-luna.

Find duplicate-code candidates

slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9 --limit 5

Compare functions across files, exclude short wrappers, and group strong matches into clusters. --limit 5 selects up to five neighbors per source function, not five clusters.

Review changed code or one module

slopdex cross-search --uncommitted --cross-file-only --min-lines 4 --threshold 0.9
slopdex cross-search --changed-since origin/main --format summary --threshold 0.9
slopdex cross-search --source-path src/services -e '^UserService\.' --format summary --threshold 0.9

These select source functions while keeping the full eligible index available for matches.

Find related code stored far apart

slopdex cross-search --cohesion --threshold 0.8 --limit 20 --format summary

--cohesion keeps the semantic matches selected by cross-search, annotates them with physical distance, and orders each source's matches from farthest to nearest. Similarity breaks distance ties.

Compare repositories

slopdex cross-search \
  --target-root /path/to/other/repo \
  --target-index /path/to/other/repo/.slopdex/index.sqlite \
  --threshold 0.9 --format summary

Both indexes refresh automatically and must use identical embedding profiles. The target is refreshed with the source command's embedding provider; target configuration supplies file-selection and description settings. Use --target-config for a non-default target config.

Inspect index health

slopdex status
slopdex index-errors --format summary
slopdex --version

status refreshes the index and reports coverage, profiles, checkpoint, and error counts. index-errors reads saved failures without refreshing or requiring credentials. --version prints the built package version.

Commands

Usage: slopdex <command> [arguments] [options].

Manual maintenance examples:

slopdex update-git
slopdex update-files src/service.ts src/model.ts
slopdex reindex-files
slopdex reindex-files --callables
slopdex delete-files src/removed.ts
slopdex update-git --target HEAD --rebuild-on-divergence
slopdex update-git --force-reindex

Location, providers, and diagnostics

Explicit relative config and index paths resolve from the current directory, not --root.

Search and analysis

Review adjacent similarity bands without repeating boundary matches:

slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9 --limit 5
slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.85-0.9 --limit 5

Refresh and recovery

Reading results

Similarity and duplicate clusters

Similarity is a model-dependent score, not a probability of duplication. Higher scores mean greater semantic resemblance. Query summaries show score path :: qualifiedName; cross-search summaries group those lines beneath each source. Functions without matches are omitted from cross-search output.

With reranking enabled, query summaries show rerankScore rerank (similarity similarity). JSON retains similarity and adds rerankScore. The similarity threshold first filters embedding candidates. Cohere and Jina receive up to five times the requested limit. The OpenAI LLM receives the configured number of top embedding results, 10 by default, or the requested result limit when it is larger. Candidates include function descriptions when available and function metadata/source code. Cross-search and cohesion analysis are not sent to rerankers.

Cluster 1 (3 functions, similarity 0.9124-0.9568)
  src/auth/session.ts:18:1 :: validateSession
  src/http/middleware.ts:42:1 :: authenticate
  src/users/user-service.ts:27:3 :: UserService.authenticate

• A cluster groups functions connected by matches. Its range covers observed links; not every pair necessarily matches directly.
• Clusters sort by member count, then name. Cluster number is not severity.
• Locations identify where to inspect behavior, callers, and architectural roles. Wrappers, adapters, tests, and separate interface implementations can legitimately resemble one another.

Physical cohesion

src/auth/session.ts :: validateSession
  0.9400  packages/http/middleware.ts :: authenticate  [distance 4]
  0.9300  src/auth/token.ts :: validateToken  [distance 1]

Run cross-search with --cohesion to put physically distant matches first. Distance is 0 within one file, 1 between files in one folder, and 1 plus directory-tree hops across folders. The option only changes the order of each source's selected semantic matches; it does not change similarity scores or establish that distant code belongs together.

For automation, pass --format json: query searches and diagnostics return JSON arrays; cross-search returns JSONL, one row per matched source. With --cohesion, each match includes physicalDistance. Results go to stdout; notices and warnings go to stderr.

System behavior

Descriptions and scoring

Descriptions are optional and disabled initially. descriptions enable persists the selected provider and model and keeps callable descriptions current on later updates. Use slopdex descriptions enable --description-provider opencode-go for OpenCode Go, or combine --description-provider and --description-model to change both. slopdex descriptions disable stops automatic updates and description-based searching/scoring while retaining cached descriptions. status exposes callable/file description counts, stale file-description count, enabled state, and profile.

Descriptions are generated in source order through one conversation per file. Instructions and complete file source form a stable prefix; Slopdex asks for the overall file description first, then each callable request and answer extends that conversation. This allows supported providers to reuse their prompt cache instead of receiving a separate duplicated file context for every callable.

Ordinary updates preserve an existing file description even when its source changes, while still refreshing callable descriptions. slopdex reindex-files explicitly regenerates stale file descriptions and their embeddings; add --callables to continue through and replace every callable description in those files.

Tree-sitter extraction, generated descriptions, and document/query vectors are content-addressed in the same SQLite database. Each validated result is committed immediately, independently of the final logical index update. If indexing is interrupted or a later provider call fails, rerunning reuses every completed result whose profile, operation, input, and source context hash still match.

When Slopdex makes external vector, description, or reranking model calls, stderr identifies the call kind, provider, and model. By default each combination is reported once per process regardless of request count. Pass --verbose, or set "verbose": true in config, to report every request. Cache hits do not produce notices because they do not call a model.

With complete descriptions, search and cross-search average one-third code similarity + one-third callable-description similarity + one-third file-description similarity. search-description averages callable and file descriptions without code. Cross-repository analysis needs complete descriptions on both sides; otherwise the entire analysis uses code-only scores. Stale file descriptions remain searchable until explicitly reindexed. Thresholds and limits apply to the selected score.

Text output labels combined scores. JSON exposes codeSimilarity, descriptionSimilarity, fileDescriptionSimilarity, and cross-search scoring mode/weights. Compare runs only with matching scoring mode, weights, embedding and description-generator profiles, threshold, and source/candidate filters.

Exclusions

Root and nested .gitignore rules apply even to tracked files and without Git. Working-tree refreshes use current rules; committed-only snapshots use the target commit's rules. Refresh removes newly excluded files and discovers newly eligible ones. Explicit update-files rejects ignored files.

Built-in exclusions: .git, .slopdex, node_modules, dist, build, coverage, vendor, generated, .venv, venv, __pycache__, .tox, .mypy_cache, .pytest_cache, and target. Config include/exclude globs narrow coverage; they cannot override built-in exclusions. Ignore exceptions cannot re-include files beneath an excluded parent directory. Files over 1 MiB are skipped unless maxFileSize is raised.

Failures and recovery

Parse, extraction, read, and file-size failures are saved while healthy callables remain searchable. Inspect them with slopdex index-errors --format summary. JSON includes paths, locations, recoverable names, messages, available source, and snapshot provenance. status reports indexingErrorCount and failedFileCount; functionCount counts searchable callables.

Saved failures trigger stderr warnings, including on cached runs, help, and cross-search targets. --ignore-errors silences warnings without clearing records. Updates retry failed files; successful indexing, deletion, or exclusion clears their diagnostics. Version output bypasses diagnostics.

Use the recovery flag named in the error: --rebuild-on-divergence for Git history changes, --force-reindex for incompatible indexes. Schema versions 6 and 7 migrate in place; earlier schemas require --force-reindex, with compatible rebuilds preserving reusable artifact caches. For provider/authentication failures, fix the reported configuration and rerun. For source-change-during-indexing errors, rerun after edits settle. Exit status is 0 on success, 2 for argument/domain errors, and 1 for other failures (or invocation without a command).

Configuration

Optional file: <root>/.slopdex/config.json. Example using Jina embeddings, OpenAI LLM reranking, and OpenCode Go descriptions (requires JINA_API_KEY, OPENAI_API_KEY for query searches, plus OPENCODE_API_KEY when descriptions are enabled):

{
  "provider": "jina",
  "model": "jina-embeddings-v4",
  "dimensions": 1024,
  "rerankingEnabled": true,
  "rerankerProvider": "openai",
  "rerankerModel": "gpt-5.6-luna",
  "rerankerCandidates": 10,
  "descriptionProvider": "opencode-go",
  "verbose": true,
  "exclude": ["**/fixtures/**"]
}

Keep keys in the environment (OPENAI_API_KEY, JINA_API_KEY, COHERE_API_KEY, OPENCODE_API_KEY). Reranker settings do not change the stored index and do not require a rebuild. Changing the embedding profile requires rebuilding with --force-reindex.

Development

• Implementation and library API