Skip to main content

ctx similar

Find existing functions similar to a description before writing new ones.

Synopsis​

ctx similar "<query>" [PATTERNS]... [OPTIONS]

Description​

The similar command searches the index for functions that already do what you are about to write. Run it before adding a new function: reusing (or extending) an existing implementation is the cheapest way to avoid duplication that ctx duplicates and ctx score would flag later.

By default the search is semantic (embedding-based, requires ctx embed); --keyword falls back to FTS5 keyword search over names, signatures, and doc comments.

Optional positional patterns restrict candidates by file path. Literal files, directories, and globs are ORed together. With no patterns, . searches the whole indexed repository.

Options​

OptionDescriptionDefault
--limit <N>Maximum number of results10
--keywordUse keyword (FTS5) search instead of embeddingsfalse
--provider <local|openai|ollama>Embedding backend for the query (must match how the index was embedded); --openai is a deprecated alias for --provider openailocal
--jsonMachine-readable output (global flag)false

Exit Codes​

CodeMeaning
0Success (informational command)
2Operational error (missing index, missing embeddings for semantic mode)

Examples​

# Before writing a retry helper, see what already exists
ctx similar "retry an operation with exponential backoff"

# Keyword mode (no embeddings needed)
ctx similar "parse config file" --keyword

# Search only command sources and shared tests
ctx similar "parse config file" src/commands/ "tests/**/*_cli.rs" --keyword

# More candidates, OpenAI embeddings
ctx similar "validate user input" --limit 20 --provider openai

# Machine-readable (standard envelope: ctx_version, command, generated_at, data)
ctx similar "token counting" --json

Caveats​

  • Semantic mode requires embeddings: run ctx embed (local model, or --provider openai/--provider ollama) first; the query provider must match how the index was embedded. Without embeddings, use --keyword.
  • Results rank by meaning, not correctness - always read the candidate before reusing it.

See Also​