| name | tensor-grep-code-audit |
| description | Use tensor-grep (tg) as the default code-audit path — callers/blast-radius/scan/doctor/map for fast AST-aware impact analysis before touching shared code. Carries the per-version CLI-contract re-verify rule. |
Tensor-Grep Code Audit
Authority: tg --help. Verified against tg 1.76.6 (tg doctor).
tg is a superset of grep/ripgrep: rg-compatible text search plus native AST
search/rewrite, symbol intelligence, persisted query acceleration, optional GPU
routing, MCP server, and agent context capsules. Default to tg over raw grep/rg
for any non-trivial code search or pre-edit audit.
When to use
- Before editing any shared symbol — run symbol intelligence first (
tg callers,
tg blast-radius, or tg impact).
- At session start / after worktree switch —
tg doctor.
- For repo orientation on an unfamiliar tree —
tg orient PATH or tg map PATH
(scope PATH on doc-heavy repos; see P10).
- On every
tg version change — re-verify CLI contract (tg <subcmd> --help).
- NOT a substitute for
codebase-audit (architectural survey).
- NOT needed for single-file edits with no external callers.
- NOT a substitute for gotcontext.ai MCP on large blobs, remote URLs, verbose CLI
output, or PR diffs — use
use-gotcontext for compression; tg for local disk.
gotcontext.ai vs tg
| Job | Tool |
|---|
| Local symbol intel, pre-edit blast-radius | tg callers, tg blast-radius |
| Large pasted doc, remote URL, git diff, pytest -v | gotcontext MCP (use-gotcontext skill) |
| MCP tools/list bloat | gc_compress_manifest (gotcontext plugin) |
The gotcontext MCP is remote and cannot read your local files. Local repo work stays on tg.
Command map (from tg --help)
Text search (rg-compatible subset)
tg PATTERN [PATH ...]
tg search [OPTIONS] PATTERN [PATH ...]
tg search --format rg --json PATH
tg search --json PATH
See tg search --help for the current validated flag subset (stable contract in
docs/CONTRACTS.md per top-level help). Notes:
-e/-f multi-pattern; -F fixed-strings; -s case-sensitive; --engine pcre2--smart-case, --hidden, --max-depth, --text honored on CPU/sidecar paths--format rg --sort path for deterministic rg-shaped output- GPU search is experimental/opt-in via
--gpu-device-ids; CPU/ripgrep is the
default speed baseline (1.58+ help wording). Current installs often ship the
CPU native front door (tg-*-amd64-cpu); with --gpu-device-ids, search may
CPU-fallback (routing_reason: gpu-auto-fallback-cpu, gpu_proof: false) rather
than accelerate. To request a CUDA front door: set
TENSOR_GREP_NATIVE_FRONTDOOR_FLAVOR=nvidia then tg upgrade (only if an nvidia
asset is published for that release — CHECKSUMS may be CPU-only). On WSL, doctor /
agent --gpu-device-ids probes can report failed_probe_path /
native_error_kind: path_not_found when the Windows native binary cannot see a
Linux tempfile — not the same as "GPU missing".
- Broad scans are refused or bounded unless scoped with paths,
--glob, --type,
--max-depth, or explicit --allow-broad-generated-scan. Unscoped whole-repo search
may timeout (~60s default) with an actionable stderr message naming
TG_RG_TIMEOUT_SECONDS / TG_SUBPROCESS_TIMEOUT_SECONDS (exit 124) — always pass
a PATH; --glob alone on a large repo may still timeout (use
tg search PATTERN PATH/ or PATH --glob '*.py').
Aggregate --json uses total_matches, total_files, matched_file_paths,
match_counts_by_file (1.51+).
Symbol intelligence — [PATH] [SYMBOL_ARG] (PATH defaults to .)
tg defs [PATH] SYMBOL
tg source [PATH] SYMBOL
tg refs [PATH] SYMBOL
tg callers [PATH] SYMBOL
tg impact [PATH] SYMBOL
tg blast-radius [PATH] SYMBOL --json
tg blast-radius-render [PATH] SYMBOL
tg blast-radius-plan [PATH] SYMBOL --json
tg imports FILE --json
tg importers FILE [ROOT] --json
Common options: --provider native|lsp|hybrid (default native on symbol cmds),
--max-repo-files N (default 2000 on most 1.42+ symbol/agent commands; map
defaults to 512 — verify per tg <cmd> --help), --json.
--deadline (1.74.0+): effectively universal (min 0.1) across symbol + AI +
coverage cmds — including defs / source / refs / callers / impact /
blast-radius / blast-radius-plan / importers / imports / inventory /
codemap / orient / map / agent / edit-plan / context / context-render /
docs-coverage. Partial JSON may include partial: true /
deadline_limit.deadline_exceeded; may exit non-zero — still parse stdout.
imports --deadline is a documented NO-OP (O(1) single-file parse; accepted for
interface parity so agents do not Click-exit-2). Prefer real bounds on scan-backed cmds.
callers also exposes --max-tests N (default 25) and --max-tokens N
(default 16000; 0 = unbounded) on 1.58+.
Positional contract (1.28+): PATH defaults to .. Preferred form is always
tg <cmd> PATH SYMBOL — scope PATH to a subdirectory on large/doc-heavy repos.
Shorthand tg callers SYMBOL works (symbol with default root .). A lone directory
without a symbol errors (tg callers core/hooks → missing symbol).
--symbol is deprecated (still accepted; warning text updated in 1.35) — pass
SYMBOL as positional: tg callers SYMBOL or tg callers PATH SYMBOL.
AI / agent workflows — [PATH] [QUERY_ARG]
tg orient [PATH]
tg map [PATH]
tg codemap [PATH]
tg inventory [PATH]
tg docs-coverage [PATH]
tg context [PATH] "query"
tg context-render [PATH] "query"
tg agent [PATH] "task" --json
tg edit-plan [PATH] "change" --json
agent, context-render, and edit-plan expose top-level validation_commands and
suggested_validation_commands (1.42+). Prefer validation_plan when present (on both
agent and edit-plan since 1.72.1+).
Templates may quote $file or {file} — spawned directly (no shell), so pipes/&&
are not interpreted. 1.39+ lexical repo-map retrieval bridges camelCase,
snake_case, and source-term queries (e.g. readBlockEnabled → read_block_enabled).
Confidence shape (1.40+): agent / edit-plan JSON use
confidence: {overall: float, downgrade_reasons: [...]} — read overall, not a bare
float. Treat overall < 0.75 as a hard stop unless validation_plan is populated
and ask_user_before_editing.required is false; inspect downgrade_reasons for
token-budget vs wrong-primary signals. 1.61+ / 1.71.3+: scoped and root agent
with a strong validation_plan commonly return overall: 0.9 and empty
downgrade_reasons. 1.74.0+: edit-plan also returns structured confidence
and ask_user_before_editing (same hard-stop rules as agent). Truncation caveat:
low --max-repo-files on agent can still yield overall: 0.9 with downgrades like
repository scan truncated… and ask_user_before_editing.required: true (hard stop)
plus suggested_scope — may exit non-zero; still parse stdout.
Validation (1.40.4+): prefer validation_plan over bare validation_commands when
present — each entry has {command, scope, runner, confidence, detection, target}.
validation_commands is the flat command list derived from the plan.
suggested_validation_commands (1.42+) is a secondary hint list when the primary plan
is empty. 1.51+: root agent on harness repos often populates validation_plan
with detected pytest commands ({command, scope, runner, confidence, detection, target}).
1.54.6+: scoped agent also populates validation_plan (including scope: symbol
with -k pytest selectors when a matching test exists).
1.72.1+: scoped edit-plan also populates structured validation_plan (same
shape as agent) plus flat validation_commands. 1.74.0+: prefer either command
for plan + confidence/ask_user_before_editing gates. When validation_plan /
validation_commands is non-empty, ask_user_before_editing.required is often
false (1.54.6+) — except under scan truncation. Cross-check primary_target before
running suggested tests. ask_user_before_editing.reasons may include
no validation command evidence when the plan is empty.
Agent guardrails (1.40.4+):
ambiguity — tie resolution metadata (status e.g. tie_resolved /
tie_requires_confirmation, tied_alternative_targets, resolution_evidence);
inspect when requires_confirmation: true.ask_user_before_editing — {required: bool, reasons: [...]}; treat required: true
as a hard stop before editing.context_consistency, omissions, route_rationale (1.54+) — extra ranking/trust
metadata; read when confidence is downgraded.call_site_evidence / related_call_sites (1.54+) — optional caller context on agent.capsule_kind / capsule_schema_version (1.54+) — capsule envelope versioning.scan_limit / scan_remediation on agent (1.47+) — same truncation metadata as
symbol commands (max_repo_files, scanned_files, possibly_truncated); read
scan_remediation when possibly_truncated: true.
Agent scoping (1.28+): on harness repos, root tg orient . may still rank bundled
skill/vendor scripts as central even with auto-deweight (1.71.3+) — use --ignore or
scope PATH for a hard exclude. Root tg agent with a specific query often ranks
correctly in 1.42+, but --ignore remains the safe default on harness repos:
tg agent . "task" --ignore 'core/skills/**' --max-files 5.
1.71.3+ suggested_scope: when the repo scan truncates, agent may return
suggested_scope: {dirs: [...], confidence: "heuristic"} (and may cite
repository scan truncated before ranking completed in downgrade_reasons). 1.72.1
dogfood: truncation also sets ask_user_before_editing.required: true (and may
exit non-zero) even when confidence.overall is still 0.9 — treat as hard stop and
re-run scoped / with higher --max-repo-files. Field is often null when the scan
completes. 1.76.6+ suggested_ignore: root orient / root agent commonly
emit whole-tree globs such as ["core/skills/**"] when auto-deweight detects a
skill/vendor island (deweighted_trees reasons include skill-tree-shape,
import-island, name-prior:skills). Prefer applying those globs (or pass
--ignore yourself). With that in place, orient . centrality on this harness
no longer ranks SEO skill scripts first. Scoped PATH or an already-applied
--ignore often leaves suggested_ignore: null.
edit-plan JSON uses primary_target / candidate_edit_targets (not targets).
source --json returns definitions with line ranges (also sources on some
builds; not a separate source_blocks array). refs --json uses references
(+ optional string_refs), not refs. callers --json / blast-radius --json use
callers (list), not call_sites. impact --json uses files / tests /
callers (not impacted_files / impacted_tests).
agent also exposes gpu_acceleration when --gpu-device-ids is set (status
not_requested / failed / used; never trust a CPU-fallback as GPU proof —
require promotion_claim / gpu_proof evidence).
AST / structural
tg scan --config sgconfig.yml
tg test
tg run PATTERN [PATH]
tg new
tg ast-info
Safety, audit, checkpoints
tg checkpoint create|list|undo
tg audit
tg audit-verify MANIFEST
tg audit-history
tg audit-diff
tg review-bundle
tg dogfood --root PATH --output report.json
tg rulesets
tg classify
Ops / infra
tg doctor [--with-lsp] [PATH]
tg session open PATH
tg session daemon start PATH
tg repair-launcher
tg lsp / tg lsp-setup
tg mcp
tg devices / tg calibrate
tg upgrade | tg update
Workflows (what to run when)
| Goal | Command |
|---|
| "What calls this?" | tg callers PATH SYMBOL --json |
| "What breaks if I change this?" | tg blast-radius PATH SYMBOL --json |
| Quick impact (files + tests only) | tg impact PATH SYMBOL --json — read preferred_command |
| "Where is this defined?" | tg defs PATH SYMBOL --json |
| "Show me the source" | tg source PATH SYMBOL --json |
| "Find all references" | tg refs PATH SYMBOL --json |
| "What does this file import?" | tg imports FILE --json (single-file, no repo scan) |
| "Who imports this file?" | tg importers FILE [ROOT] --json — FILE vs cwd, ROOT = scan bound only |
| Unfamiliar repo, need bearings | tg orient PATH --json or tg map PATH (scope PATH) |
| Persisted browsable code map | tg codemap PATH --out DIR --json then --check; harness: --ignore 'core/skills/**' |
| Harness repo: exclude skill trees | tg orient . --ignore 'core/skills/**' or scope PATH |
| Doc drift (files vs CLAUDE.md) | tg docs-coverage PATH |
| Doc drift CI gate | tg docs-coverage PATH --check (exit 1 if uncovered) |
| Doc drift fix table | tg docs-coverage PATH --fix (paste-ready Markdown) |
| Exclude stub trees from coverage | tg docs-coverage PATH --ignore 'vendor/**' (repeatable) |
| Stale doc references | tg docs-coverage PATH --stale |
| Before editing, get a capsule | tg agent PATH "task" --json — read validation_plan, ask_user_before_editing |
| Plan an edit with validation | tg edit-plan PATH "change" --json — read validation_plan, confidence, ask_user_before_editing (1.74.0+) |
| Text search (prefer over grep) | tg search PATTERN PATH (always scope PATH) |
| Session health | tg doctor |
| Release / agent-readiness check | tg dogfood --root PATH --output report.json --json |
| After risky rewrite | tg checkpoint create then tg audit-verify |
P1: CLI contract regression trap
Run tg <subcmd> --help per-subcommand on EVERY version change. rc=0 is insufficient.
Keep a contract test that asserts positional shapes and that live output is trusted.
If --help shows DEPRECATED, migrate immediately.
P2: Trust fields — result_incomplete and low confidence are hard stops
On any symbol command with --json, inspect before proceeding:
result_incomplete: true → truncated; widen --max-repo-files and re-run.- stderr may also print
INCOMPLETE RESULT with the repo-file cap — treat as hard stop
even if you skipped --json.
not_found: true on symbol commands or importers → didn't resolve; don't assume
zero callers/importers. importers may exit 0 or non-zero with valid JSON when
not_found — always parse stdout. 1.63+: tg importers FILE ROOT resolves
FILE against cwd (never joins onto ROOT); ROOT is the scan boundary only.graph_trust_summary.confidence (blast-radius, 1.45+) — values include strong,
moderate, etc. Read the full summary: evidence_counts.parser_backed,
evidence_counts.heuristic, evidence_counts.by_ref_kind, provenance,
resolution_gaps_present, edge_kind. moderate + resolution_gaps_present: true
warrants caution even on low caller counts.
moderate with parser_backed > 0 and low caller count may still be actionable;
resolution_gaps_present: true warrants caution.graph_completeness, provider_status, provider_agreement, ranking_quality.scan_limit.possibly_truncated / truncation_cause — explicit cap metadata (1.28+).partial: true / deadline_limit.deadline_exceeded (1.39+ --deadline where
supported — see command map; min 0.1s) — bounded partial result; command may exit
non-zero even when JSON is present.confidence.overall + downgrade_reasons on agent (1.40+) — require
overall >= 0.75 OR a non-empty validation_plan with ask_user_before_editing.required: false before trusting primary_target; 1.54.6+ may ship validation at 0.75 with
validation-corroborated resolution in downgrade_reasons; 1.61+ scoped agent
can reach 0.9 with empty downgrades when validation corroborates.ask_user_before_editing.required: true on agent (1.40.4+) — hard stop; read reasons.
Often false when validation_plan is populated (1.54.6+).agent.scan_limit.possibly_truncated (1.47+) — hard stop; read scan_remediation.ambiguity.requires_confirmation or unresolved tie on agent (1.40.4+) — confirm
primary_target against tied_alternative_targets before editing.
callers: [] without truncation is still NOT "dead code" (see P7).
P3: Blast-radius pre-change gate
tg blast-radius PATH SYMBOL --json BEFORE editing a shared symbol. Use --json for
the machine caller graph — blast-radius-render is prose-only, not the graph payload.
Use:
blast_radius_score — headline impact metriccallers, caller_tree, affected_files, tests, test_matchesgraph_trust_summary — confidence, evidence_counts, provenance,
resolution_gaps_present (1.45+)--mermaid for a doc-friendly caller graph. 1.74.4+: --json --mermaid keeps
the machine graph and adds a top-level mermaid string (graph TD …). --mermaid
alone still prints Mermaid text on stdout (no JSON).blast-radius-plan when you want the planning shape without source snippets
tg impact returns preferred_command: "blast-radius" and trust_level: "planning-signal"
when caller attribution is needed — follow that guidance.
Thresholds (direct callers / affected files):
- <5 → proceed
- 5–20 → document scope
-
20 or low graph_trust_summary.confidence / confidence.overall → council / operator sign-off
P4: Positional order — PATH then SYMBOL (PATH defaults to .)
Symbol commands: tg <cmd> [PATH] [SYMBOL]. Query commands: tg <cmd> [PATH] "query".
1.28+: tg callers SYMBOL is valid shorthand (searches from .). For large repos,
always prefer tg callers PATH SYMBOL to avoid repo-file cap truncation.
Never rely on deprecated --symbol.
P5: Always scope searches
Broad generated-root / workspace-root scans are refused or bounded by default. Always pass
a PATH. Opt-in only with --allow-broad-generated-scan when you truly need it.
Start narrow (tg search PATTERN api/app/), widen one level on empty results.
P6: tg doctor at session start
Run tg doctor after worktree switches. --with-lsp is default; provider
availability ≠ navigation proof — read health_status / health_check.
GPU note (1.27+ / 1.76.6+): search_ready=False is expected while GPU search
is experimental/opt-in — text and AST search are unaffected. Read tier:
(installed / usable / promotion_proof) and, on probe failure,
search_runtime_probe.status (e.g. failed_probe_path) plus
native_error_kind (path_not_found on WSL tempfile probes). tg calibrate
requires a CUDA-enabled front door and now prints how to request
TENSOR_GREP_NATIVE_FRONTDOOR_FLAVOR=nvidia + tg upgrade (falls back to CPU if
no nvidia asset is published for that release).
AST cache (1.28+): cold cache adds ~20–30s first-query latency — run tg map PATH
once; doctor shows ast_cache.exists and remediation hint.
Warm repeated work: tg session daemon start PATH (or just run a symbol query —
autostart will spawn).
1.58+ / 1.68+ / 1.76.6+: TG_SESSION_DAEMON_AUTOSTART is default-ON for
defs/impact/refs/callers/blast-radius (auto-spawns non-blocking on miss;
first call per root pays cold-start). After warm traffic, tg doctor should show
session_daemon: running and symbol JSON may include session_id,
daemon_response_cache (hit/miss), and serve_cache. Cold doctor can still
report running: false / stopped before the first autostart. Set 0/false/off
to opt out; forced off under CI/GITHUB_ACTIONS. Idle shutdown via
TG_SESSION_DAEMON_IDLE_SECONDS (default 900). tg session importers FILE is the
cached-session zero-reparse reverse-import path.
Index state: .tensor-grep/ and _tg_refs/ at workspace root.
Code map (1.68+): tg codemap PATH --out DIR writes index.md + per-folder pages
_coverage.json; prefer live callers/defs/refs for authoritative current
data — use the map for orientation. tg codemap PATH --out DIR --check exits 1 when
stale. 1.69+: --ignore GLOB (repeatable) excludes vendor/skill trees from the
generated pages; --deadline returns a partial map instead of running unbounded.
P7: Zero callers ≠ dead code
AST graph misses string registrations, decorator handlers, dispatch tables,
and some dynamic import fallbacks. Cross-check with tg refs, tg importers FILE,
or scoped tg search before deleting.
tg imports / tg importers are cheap file-dependency primitives. 1.71+:
sys.path.insert sibling modules often resolve (provenance: sys-path-insert,
external: false, per-edge resolved path + top-level resolved_files) and
importers can return the reverse edge. Still verify when resolved is null /
not_found: true — string-keyed registries and getattr dispatch remain blind spots.
P8: Assert the REAL JSON payload shape
Dogfood real command output in contract tests. The 1.35+ envelope (schema_version: 1)
uses result_incomplete, output_limit, scan_limit, graph_trust_summary,
blast_radius_score — not legacy field names.
P9: Windows shell escaping
PowerShell double quotes expand $NAME before tg sees the pattern — use single
quotes or escape $. In cmd.exe, quote or caret-escape |, &, <, >, ^.
Run tg doctor for shell_escaping_guidance tailored to your shell.
P10: Doc-heavy repos — scope orient/agent/map
Repos with bundled skill/vendor trees (e.g. harness libraries) may still need
PATH/--ignore scoping. 1.71.3+: orient auto-deweights detected
vendor/skill/generated CODE subtrees by default (auto_deweight: true,
deweighted_trees lists path+reasons). 1.76.6+: deweight often covers the
whole skills tree (reasons include skill-tree-shape) and both orient and
root agent emit suggested_ignore: ["core/skills/**"] — apply that (or pass
--ignore 'core/skills/**') and centrality on this harness ranks hooks/scripts
first instead of SEO skill packages. Pass --no-auto-deweight only when debugging
ranking.
Hard exclude: repeatable --ignore on orient and agent (1.39+):
tg orient . --ignore 'core/skills/**', tg agent . "task" --ignore 'core/skills/**'.
Still valid: scope to the code subtree — tg orient core/hooks, tg map providers/agy.
For doc-drift on harness repos, exclude bundled skill trees:
tg docs-coverage . --ignore 'core/skills/seo/**' --check.
Environment overrides (common)
| Var | Purpose |
|---|
TG_FORCE_CPU | Force CPU routing for search |
TG_RG_PATH | Path to ripgrep executable |
TG_SIDECAR_PYTHON | Python executable for sidecar-backed commands |
TG_SIDECAR_TIMEOUT_MS | Sidecar command timeout |
TG_HELP_PROBE_TIMEOUT_MS | Native --help passthrough probe timeout (default 3000) |
TG_LSP_PROVIDER | Override LSP semantic provider mode |
TG_RG_TIMEOUT_SECONDS / TG_SUBPROCESS_TIMEOUT_SECONDS | Search/subprocess timeouts |
TG_NATIVE_TG_BINARY | Native front door for Python-backed commands |
TG_SESSION_DAEMON_AUTOSTART | Default-ON warm-daemon for symbol cmds; set 0 to opt out (forced off in CI) |
TG_SESSION_DAEMON_IDLE_SECONDS | Daemon idle shutdown (default 900) |
TENSOR_GREP_NATIVE_FRONTDOOR_FLAVOR | Set nvidia to prefer CUDA native front-door assets on tg upgrade (CPU fallback if unpublished) |
TENSOR_GREP_DEVICE_IDS | Comma-separated GPU IDs |
TENSOR_GREP_CLASSIFY_PROVIDER | Set cybert for CyBERT/Triton classify |
TENSOR_GREP_LSP_OPERATION_BUDGET_SECONDS | LSP provider time budget |
TENSOR_GREP_SESSION_RESPONSE_CACHE_MAX_BYTES | Bound agent-loop session response cache |
TG_MCP_ALLOW_VALIDATION_COMMANDS | Set 1 to let MCP tg_rewrite_apply run lint/test cmds |
Full list: tg --help → Environment overrides section.
