| name | tensor-grep-find-and-route |
| description | Use when vocabulary-mismatched queries need whole-repo hybrid search via tg find (BM25 + optional dense RRF, no regex pre-filter), or when verifying context-render vs edit-plan target agreement with tg route-test before trusting an edit plan. Distinct from tg search --rank/--semantic (those re-rank an existing regex match set). |
tensor-grep find + route-test
Verified against tg 1.110.14 (2026-08-11; prior full dogfood 2026-07-21 WSL workspace sweep at v1.91.0).
When to use
| Need | Command |
|---|
| Natural-language / mismatched vocabulary over a whole repo (no pattern pre-filter) | tg find "query" PATH --json |
Confirm context-render and edit-plan agree on primary file/symbol/line | tg route-test PATH "query" --json |
Do not use tg find as a grep replacement (--format rg is intentionally absent). Prefer scoped PATH (REPO/src) first.
tg find
tg find "session daemon timeout handling" REPO/src --deadline 20 --json
tg find "session daemon timeout handling" REPO --deadline 30 --json
- Multi-word NL examples like the above are dense-favored by default (flip SHIPPED #191/#634,
first released v1.79.0; re-verified 2026-08-12 against v1.110.14): with
TG_FIND_DENSE_WEIGHT
unset (or malformed/non-finite), a genuinely multi-word query gets the adaptive 5.0 weight;
single-token queries stay pinned at 1.0. TG_FIND_DENSE_WEIGHT=1.0 is the explicit BM25-only
(equal-weight) opt-out. See tensor-grep-semantic-search-campaign STATUS UPDATE 4.
- Bounded by default (
--max-repo-files, --deadline, internal chunk cap).
- Truncation →
result_incomplete + exit 2 (never silent partial-as-complete).
- Bare
tg find "query" with no PATH does NOT hit the search fast-refuse — find defaults PATH to
. (it is not bootstrap-intercepted; the IMPLICIT_SEARCH_WALK_FILE_CEILING=1500 fast-refuse is a
tg search front-door behavior, v1.92.3). find bounds itself via --max-repo-files (default 2000)
plus --deadline/chunk caps, and marks truncation honestly (result_incomplete + exit 2). Still:
always scope tg find to a PATH — for ranking quality and so a big root doesn't truncate the corpus.
- Scale evidence:
tg find's repo walk shares the exact same _iter_repo_files walker as
orient/inventory/search (_execute_find calls it directly). A 300k+-file multi-project
workspace dogfood found deadline-bounded surfaces on that walker hold up well in general; the one
known low-priority edge — a non-lazy os.scandir read of a single pathological, huge directory
inside _iter_repo_files that can outrun --deadline before the per-file check fires — was
observed via inventory --deadline but applies equally to find --deadline (same walk call, same
missing mid-scandir check). Rare; another reason to scope tg find to a PATH rather than lean on
--deadline alone at repo root.
- Dense leg: prefer
tg install-dense (one-shot pip + pinned potion-code-16M). Without it, find is
BM25-only and reports rank_fallback_reason — supported, not silent. The fallback message is now the
literal retrieval_dense.py string (A12(a), v1.93.0/#705): semantic ranking unavailable: model2vec not installed -- run `tg install-dense` (or pip install 'tensor-grep[semantic]') — every
dense-absent hint across the CLI leads with tg install-dense the same way, not just this one.
- Which leg ran is reported IN the payload (
src/tensor_grep/cli/main.py:1663-1664):
routing_backend is HybridFindBackend when the dense index loaded, else Bm25FindBackend;
routing_reason is find_bm25_dense_rrf or find_bm25_only. Both are REQUIRED by
tests/schemas/tg_output.schema.json (typed minLength: 1), so a null there is a contract
violation, not a shrug — they were null on every tg find --json payload until v1.111.6.
rank_fallback_reason and routing_reason are DIFFERENT signals and must not be conflated:
routing_reason says WHAT RAN, rank_fallback_reason says WHY the dense leg is absent. A
consumer that reads only one of them cannot distinguish "hybrid ran" from "BM25 ran because
model2vec is missing".
- Dogfood (1.91.0):
find_src ~8.4s PASS (BM25 before install-dense); find_src_postdense ~21s PASS
(no fallback). Not re-collected since v1.91.0 — before citing these as current, re-run on the
shipped wheel as an isolated cold-process pass per case: a warm end-to-end dogfood run can hide a
since-changed function's real cost in either direction, and find_src_postdense bundles the
one-time potion-code-16M model load, so its warm/cold status matters.
tg route-test
tg route-test REPO/src "improve session daemon timeout" --json
- Emits
agreement + per-field agreement_details (file/symbol/line).
- Dogfood (1.91.0):
agreement=true on tensor-grep/src (~27s alone; the old "can exceed 60s under WSL suite load — budget 90s" guidance is SUPERSEDED by the default 60s deadline — see the next bullet). This evidence predates the #693/#250 primary-target ranking fix (v1.91.2) that it is meant to validate — re-collect the agreement=true proof on a current version before citing it as current confirmation of post-fix routing agreement.
- SUPERSEDED (2026-08-12 retention pass, verified against v1.110.14 / base
568065a): since #672 (first released v1.81.21 — NOT v1.100.0), route-test defaults to a 60s wall-clock --deadline, reusing DEFAULT_AGENT_CLI_DEADLINE_SECONDS = 60.0 (defined in agent_capsule_constants.py, re-exported by agent_capsule.py; find it with grep -rn "DEFAULT_AGENT_CLI_DEADLINE_SECONDS = " src/tensor_grep/cli/ — deliberately NO line number, because this citation previously pinned agent_capsule.py:34, which is an unrelated import after the constants split; wired at grep -n "agreement_basis" src/tensor_grep/cli/main.py — deadline defaulting :11037-11081, partial stamping :10982-10993). Under defaults it therefore CANNOT exceed ~60s: when either route's build is truncated, the payload additively stamps partial=true, partial_reason="deadline", deadline_limit (which side(s) truncated), and agreement_basis="partial" — the tell an agent MUST check before trusting agreement at face value; an agreement computed from one or two truncated sides exits 2 and must not read as a full-confidence verdict. A complete run omits all four fields (byte-identical to the pre-#672 payload). --deadline N overrides the default; --no-deadline restores unbounded running (only then can it exceed 60s).
- Use before trusting an edit-plan primary when routes might diverge.
- For the routine single-target case,
tg prepare already returns a primary_target + confidence in one call and explicitly supersedes the multi-step orient→search→→→→→ loop (see ) — reach for directly when you need the explicit per-field breakdown, or when reconciling separately-made / calls.
Related
tensor-grep, tensor-grep-enterprise-agent, tensor-grep-semantic-search-campaign (build history for dense/RRF)tensor-grep-prepare — one-call edit readiness that already covers the routine route-test-equivalent check; prefer it for ordinary edits, reach for tg route-test directly for the explicit per-field breakdowntg search --rank / --semantic re-rank regex hits — different contract than tg find
