Rawq

rawq — Agent Usage Guide

Context retrieval engine. Semantic + lexical hybrid search over codebases. Returns ranked code chunks with file paths, line ranges, scope labels, and confidence scores.

When to use rawq

Use rawq when you don't know where to look. Use grep/read when you already know the file or exact string.

Query style matters

rawq blends semantic (embedding) and lexical (BM25) search. How you phrase the query changes which mode dominates.

Use natural language for concepts — this is where rawq beats grep:

rawq search "how does the app handle authentication failures" .
rawq search "database connection pooling and retry logic" .
rawq search "where are environment variables validated" .

Use identifiers only for exact symbol lookup:

rawq search "fn parse_config" .
rawq search "class DatabaseClient" .

Do NOT use grep-style keyword queries with rawq. These produce worse results:

# BAD — grep-style keywords, rawq can't infer intent
rawq search "auth error" .
rawq search "db pool" .

# GOOD — natural language, rawq understands the concept
rawq search "how does authentication error handling work" .
rawq search "database connection pool management" .

The more descriptive your query, the better semantic search works. Single keywords trigger lexical-dominant mode which is just BM25 — no better than grep.

Use filtering options

Agents often search the entire codebase when they already know constraints. Use filters to narrow results and improve relevance:

# Filter by language — skip irrelevant file types
rawq search "parse config" . --lang rust
rawq search "API endpoint" . --lang typescript

# Exclude patterns — skip tests, generated code, vendored deps
rawq search "database" . --exclude "*.test.*" --exclude "vendor/*"

# Force search mode when you know what you need
rawq search -e "reconnect" .          # lexical only — exact keyword match
rawq search -s "how does caching work" .   # semantic only — concept search

# Re-rank for better precision on ambiguous queries
rawq search "error handling" . --rerank

# Text weight — boost docs/comments when searching for explanations
rawq search "how to configure" . --text-weight 1.0

# Token budget — control how much context is returned
rawq search "auth" . --token-budget 2000 --json

Commands

search — find relevant code

rawq search "query" [path]                    # hybrid search (default)
rawq search "query" [path] --json             # structured JSON for parsing
rawq search "query" [path] --lang rust        # only Rust files
rawq search "query" [path] --exclude "test*"  # skip test files
rawq search "query" [path] --top 5            # limit to 5 results
rawq "query" [path]                           # shorthand (no subcommand needed)

Key flags:

• --top N — number of results (default 10)
• --context N — surrounding context lines (default 3)
• --json — structured output with all fields
• --stream — NDJSON streaming (one result per line)
• --lang X — filter by language
• --exclude "glob" — skip matching files
• -e / -s — force lexical / semantic mode
• --rerank — two-pass keyword overlap re-ranking
• --text-weight F — weight for text/markdown chunks (default 0.5, use 1.0 for docs)
• --token-budget N — max tokens in results
• --full-file — include full file content in results

map — codebase structure

rawq map .                  # definitions with hierarchy
rawq map . --depth 3        # deeper nesting
rawq map . --lang rust      # only Rust files
rawq map . --exclude "test*" # skip test directories
rawq map . --json           # structured output

Use to orient in an unfamiliar codebase before searching. Filter with --lang and --exclude to avoid noise from irrelevant files.

diff — search within changes

rawq diff "query" .                # unstaged changes
rawq diff "query" . --staged       # staged changes
rawq diff "query" . --base main    # diff vs branch

JSON output format

{
  "schema_version": 1,
  "model": "snowflake-arctic-embed-s",
  "results": [
    {
      "file": "src/db.rs",
      "lines": [23, 41],
      "display_start_line": 23,
      "language": "rust",
      "scope": "DatabaseClient.reconnect",
      "confidence": 0.91,
      "content": "...",
      "context_before": "...",
      "context_after": "...",
      "token_count": 45
    }
  ],
  "query_ms": 8,
  "total_tokens": 45
}

Workflow

1. rawq map . — understand the structure
2. rawq search "descriptive query" . --json — find relevant code
3. Read the top results' files for full context
4. Act on what you found

rawq narrows down which files matter. Read those files, not everything.

Source: auyelbekov/rawq — distributed by TomeVault.