Search - HQ + Codebase Search

Semantic + full-text search across HQ and indexed codebases using qmd. Falls back to Grep if qmd is unavailable.

Input: The user's search query, with optional flags.

Parse Arguments

Extract from the user's input:

• query — search text (everything except flags)
• --mode — search (BM25), vsearch (semantic), query (hybrid). Default: search
• -n — result count (default: 10)
• -c — collection name (e.g. hq-infra, hq-workers, {product}). Default: auto-detect or all collections
• --full — show full content of top result

Company Auto-Detection

If -c was NOT explicitly provided, infer the active company from context:

1. cwd: If inside companies/{name}/ or repos/private/ matching a company repo per companies/manifest.yaml → use that company's collection
2. Active worker: If /run {worker} is active and worker has company: field → use that company's collection
3. Recent files: If recent file access is scoped to a single company → use that company's collection
4. Fallback: No collection flag (search all)

Available collections: hq-infra (commands/skills/policies), hq-workers (worker defs), hq-knowledge (shared knowledge), hq-projects (PRDs), {product} ({PRODUCT} codebase), + one per company. Omit -c to search all.

When auto-detected, display: (auto: {company}) in results header.

Check qmd Availability

which qmd 2>/dev/null && qmd --version 2>/dev/null

If qmd is not available, skip to Fallback section.

Execute Search

Run the matching qmd command. Add -c $COLLECTION if a collection was specified or auto-detected.

Default in-turn path is BM25. qmd vsearch / qmd query auto-download a ~300MB–2GB GGUF model on first use and have stalled a single Windows HQ prompt for more than two hours. Only use those modes when the model is already on disk.

Default (BM25 full-text — no model download):

qmd search "$QUERY" -n $N --json [-c $COLLECTION]

Semantic (conceptual match) — only if embeddings are already cached:

In the same Bash call as the availability check, probe the GGUF cache and skip vsearch when it is empty:

MODELS="${QMD_MODELS_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/qmd/models}"
if ls "$MODELS"/*.gguf >/dev/null 2>&1; then
  qmd vsearch "$QUERY" -n $N --json [-c $COLLECTION]
else
  echo "qmd embeddings not cached; using BM25. Run: hq index background"
  qmd search "$QUERY" -n $N --json [-c $COLLECTION]
fi

Hybrid (BM25 + vector + re-rank) — same cache gate as semantic:

MODELS="${QMD_MODELS_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/qmd/models}"
if ls "$MODELS"/*.gguf >/dev/null 2>&1; then
  qmd query "$QUERY" -n $N --json [-c $COLLECTION]
else
  echo "qmd embeddings not cached; using BM25. Run: hq index background"
  qmd search "$QUERY" -n $N --json [-c $COLLECTION]
fi

Never run qmd pull, qmd embed, or a cold qmd vsearch/qmd query in the foreground of a user turn. To build embeddings: hq index background, or qmd pull/qmd embed with run_in_background: true. On Windows, keep this probe and the search in one Bash call — each spawn is expensive.

Empty Result Escalation

An empty BM25 result does not mean the content is missing. BM25 only matches words that appear verbatim in the indexed text. Before using Fallback:

1. If the GGUF cache is present (same probe as above), rerun as qmd query "$QUERY" -n $N --json [-c $COLLECTION].
2. Otherwise rerun qmd search with 2–3 rephrasings: synonyms, the likely document title, the artifact type (memo, deck, deploy, report).
3. If a company collection was auto-detected and a {company}-signals collection exists, search it too.

Use Fallback only after these also return nothing.

Display Results

Parse JSON output. Display:

Search: "{query}" (mode: {mode}, collection: {collection or "all"})

Results:
  1. [0.92] hq: core/knowledge/public/Ralph/02-core-concepts.md
     "Ralph methodology emphasizes small loops with human checkpoints..."

  2. [0.84] {product}: libs/core/src/auth/middleware.ts
     "export function authMiddleware..."

  3. [0.71] hq: core/workers/public/dev-team/architect/skills/design-review.md
     "Architecture review following Ralph back-pressure patterns..."

{n} results. Use --full to show top result content.

• Score in brackets
• Collection prefix + relative path (strip qmd://{collection}/ prefix)
• Snippet truncated to ~100 chars

Full Content

If --full flag, after listing results, read the top result file with the Read tool.

Fallback

If qmd is unavailable, errors, or the Empty Result Escalation above also returned nothing:

Use the Grep tool to search file contents:

• Search pattern: the query text
• Search directories: core/knowledge/, companies/, core/workers/, .claude/commands/, workspace/
• Show matching file paths

Display: "qmd unavailable, falling back to Grep"

If Grep is also unavailable, run:

grep -rl "$QUERY" ~/HQ/knowledge/ \
  ~/HQ/companies/ \
  ~/HQ/workers/ \
  ~/HQ/.claude/commands/ \
  ~/HQ/workspace/ 2>/dev/null | head -20

Examples

search ralph                                    # BM25 keyword search (default, all collections)
search "how do workers execute" --mode vsearch  # Semantic across all
search auth middleware -c {product}                   # Search {PRODUCT} codebase only
search "webhook handler" -c {product} --mode vsearch  # Semantic search in {PRODUCT}
search {company} brand --mode query            # Hybrid with re-ranking
search stripe -n 20                             # More results
search authentication --full                    # Show top match content
search "brand guidelines" -c {company}         # Search {company} knowledge only
search "recovery metrics" -c {company}        # Search {Product} knowledge only
# If cwd is companies/{company}/:
search "case study"                             # Auto-detects → -c {company}

Notes

• Default search mode is fastest and does not download models — use it for in-turn HQ search
• Use --mode vsearch for conceptual/semantic queries only when ~/.cache/qmd/models/ already has a GGUF; otherwise fall back to qmd search
• Use --mode query for highest quality (slower, uses LLM re-ranking) only when that same cache is present
• Never download GGUF models in a user-facing turn. Use hq index background instead.
• Use -c to scope to a collection: hq-infra, hq-workers, hq-knowledge, hq-projects, {product}, + company collections (run qmd status for full list)
• Without -c, auto-detects company from context; falls back to all collections
• Scores 0.0–1.0; above 0.5 is a good match
• Run qmd update after adding new content
• For exact pattern matching in code (imports, function names), use Grep directly