Search

---
name: search
description: Search HQ content and indexed repos with qmd, falling back to grep.
allowed-tools: Read, Grep, Bash(qmd:*), Bash(grep:*), Bash(ls:*)
---

# 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

```bash
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):**
```bash
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:

```bash
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:**
```bash
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.

## 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 or errors:

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:
```bash
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