Searching Effectively

Searching Effectively

columbus search returns ranked, LLM-ready context across code, memory, and the epic → story → task hierarchy. It is semantic: your query is embedded on-device and matched by vector similarity, then re-ranked by deterministic heuristics — so it finds things by meaning, not just exact words.

Basic search

$ columbus search "how are credentials checked"
1. Check  [method]  (score 0.51, semantic match)
   internal/auth/auth.go:9
2. Authenticator  [class]  (score 0.46, semantic match)
   internal/auth/auth.go:6
...

Each hit carries a grain (symbol / file / member), a score, and a why — semantic match for vector hits, or a heuristic reason (exact name match, signature match, …) when keyword signal dominates. Same query, same model → same order.

If no onnxruntime runtime is present, search degrades to keyword (FTS) ranking; columbus doctor shows which mode you're in. See Installation.

Choose what to search: --kind

code | memory | epic | task | all (default all).

columbus search "port"  --kind code      # only the codebase
columbus search "WAL"   --kind memory    # only durable memory
columbus search "ship"  --kind epic      # only epics
columbus search "FTS"   --kind task      # only tasks

Searching memory and work alongside code is how an agent checks "have we already decided this / is there work touching this?"

Control size: --limit and --context-lines

Flag	Default	Effect
--limit N	15	Maximum number of results (global flag)
--context-lines N	3	Lines of context around matched ranges

columbus search "config" --limit 5 --context-lines 1

Locate-first, then pull bodies: --snippets

By default search returns locations, signatures and scores (the cheap "where to look" map). Add --snippets to attach code bodies inline (cap with --snippet-lines N), or pull one body on demand with columbus show symbol.

Shape the output: --json / --llm

columbus search "parse config" --llm     # markdown for a context window
columbus search "parse config" --json    # machine contract (see JSON Contract page)

All three formats are projections of the same typed result. See Output Modes.

Tips

• Lean into natural language — "where do we validate tokens" beats guessing the exact identifier. Semantic retrieval surfaces conceptually related code.
• For dependency edges ("what imports this?"), use graphs.
• Pair with Navigating Code (show) to pull full bodies once you've located the target.
• If a brand-new symbol isn't found, your index may lag — run columbus reindex --changed (see Keeping the Index Fresh).

Related

Command: search · Command: graphs · Navigating Code