Tensor Grep Code Audit

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

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 ...]                    # bare pattern → treated as tg search
tg search [OPTIONS] PATTERN [PATH ...] # validated common rg-compatible subset
tg search --format rg --json PATH        # ripgrep JSON Lines events
tg search --json PATH                    # tensor-grep aggregate JSON

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   # exact definition locations (--class to disambiguate)
tg source      [PATH] SYMBOL   # exact source blocks for a definition
tg refs        [PATH] SYMBOL   # Python-first symbol references
tg callers     [PATH] SYMBOL   # JSON key `callers` (list) + likely tests — not `call_sites`
tg impact      [PATH] SYMBOL   # planning signal: `files`/`tests`/`callers` (+ preferred_command)
tg blast-radius [PATH] SYMBOL --json   # callers + caller_tree + affected_files + score (use --json)
                                     # --mermaid alone: Mermaid graph TD on stdout
                                     # --json --mermaid (1.74.4+): JSON graph + `mermaid` string field
tg blast-radius-render [PATH] SYMBOL   # prose paste-in bundle (not the machine graph)
tg blast-radius-plan   [PATH] SYMBOL --json  # planning bundle, no source snippets (--deadline)
tg imports     FILE --json             # forward file deps for ONE file (O(1), no repo scan)
                                     # 1.71+: resolves sys.path.insert sibling modules
                                     # (provenance: sys-path-insert; per-edge `resolved`
                                     # + top-level `resolved_files`)
tg importers   FILE [ROOT] --json      # reverse file deps (#74 primitive; bounded scan)
                                     # FILE resolves against cwd, NEVER joined onto ROOT
                                     # (dogfood #104 / 1.63+). ROOT is scan boundary only.
                                     # may exit 0 or non-zero when not_found:true — still parse stdout
                                     # 1.71+: finds reverse edges for sys.path-hacked siblings

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]              # one-call orientation capsule (central files, entry points)
                                     # --ignore GLOB (repeatable) hard-excludes vendor/skill trees
                                     # --no-auto-deweight (1.71.3+): auto de-weight of detected
                                     # vendor/skill/generated CODE subtrees is ON by default
                                     # (lowers score only; never excludes — JSON: auto_deweight,
                                     # deweighted_trees). Hard exclude still needs --ignore.
                                     # --deadline
tg map         [PATH]              # deterministic repo map (files/symbols/imports/tests)
                                     # --deadline
tg codemap     [PATH]              # persisted browsable folder→file→symbol map (1.68+)
                                     # --out DIR (default /docs/code-map), --check (freshness),
                                     # --ignore GLOB (repeatable, 1.69+), --deadline, --json
tg inventory   [PATH]              # single-pass inventory (files, bytes, languages)
                                     # --json: totals.files / totals.bytes (not file_count)
                                     # --deadline SECONDS (min 0.1) for partial manifest on huge trees
tg docs-coverage [PATH]            # source files not in CLAUDE.md/README/AGENTS.md
                                     # --ignore GLOB (repeatable), --fix, --stale, --check,
                                     # --deadline (1.74.0+)
tg context     [PATH] "query"      # ranked context pack for edit planning (--deadline)
tg context-render [PATH] "query"   # prompt-ready context bundle (--deadline/--profile)
tg agent       [PATH] "task" --json # actionable capsule: targets, snippets,
                                    # validation_commands, validation_plan,
                                    # suggested_validation_commands, rollback,
                                    # confidence, ambiguity, ask_user_before_editing,
                                    # scan_limit, scan_remediation
                                    # --ignore GLOB (repeatable); --deadline
tg edit-plan   [PATH] "change" --json # machine-readable edit plan +
                                    # validation_commands, validation_plan (1.72.1+),
                                    # suggested_validation_commands,
                                    # confidence + ask_user_before_editing (1.74.0+)
                                    # --deadline; --profile (1.54+)

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      # bounded AST scan
tg test                            # structural rule tests
tg run PATTERN [PATH]              # AST slice + guarded rewrite (tg run --help)
                                   # PowerShell: single-quote patterns with $ captures
tg new                             # create bounded AST workflow project/rule/test
tg ast-info                        # supported AST language identifiers

Safety, audit, checkpoints

tg checkpoint create|list|undo     # edit checkpoints
tg audit                           # parent: audit-verify | audit-history | audit-diff | review-bundle
tg audit-verify MANIFEST           # verify rewrite audit manifest digest/chain
tg audit-history                   # list audit manifests (newest first)
tg audit-diff                      # semantic diff between two manifests
tg review-bundle                   # create/verify enterprise review bundles
tg dogfood --root PATH --output report.json   # agent-readiness gate (no bare PATH arg)
                                     # --progress auto|always|never, --timeout-s N
tg rulesets                        # built-in security/compliance rule packs
tg classify                        # log classification (local default; CyBERT opt-in)

Ops / infra

tg doctor [--with-lsp] [PATH]      # system, GPU, cache, daemon, launcher diagnostics
                                     # --with-lsp is DEFAULT; inspect health_status
tg session open PATH               # cached edit-loop session
tg session daemon start PATH       # warm daemon for repeated queries
tg repair-launcher                 # fix Windows launcher shadowing native tg.exe
tg lsp / tg lsp-setup              # structural search LSP + provider install
tg mcp                             # MCP server for AI assistants
tg devices / tg calibrate          # GPU inventory / CPU-vs-GPU crossover
tg upgrade | tg update             # upgrade in place

Workflows (what to run when)

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 metric
• callers, caller_tree, affected_files, tests, test_matches
• graph_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)

Full list: tg --help → Environment overrides section.