// Use when searching code, logs, or repositories with tensor-grep; validating rg or AST parity; using tg MCP tools; checking GPU/search routing; or producing agent-friendly context, source, refs, or blast-radius output.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | tensor-grep |
| description | Use when searching code, logs, or repositories with tensor-grep; validating rg or AST parity; using tg MCP tools; checking GPU/search routing; or producing agent-friendly context, source, refs, or blast-radius output. |
release_docs_current_tag: v1.9.4
As of 2026-05-09, the current released version is v1.9.2. Stable installer, PyPI metadata refresh, release-native asset publication, managed-native front-door refresh after tg upgrade, native-front-door CLI parity for advertised public flags, Windows .cmd quoted-pattern launcher handling, native-first Windows PATH ordering, top-level validation-command JSON, local default classify, GPU scale benchmark correctness gates, launcher-route observability, benchmark launcher attribution, scoped GPU device probing, benchmark launcher warnings, the opt-in tg agent Actionable Context Capsule, mixed-language capsule confidence/validation alignment, GPU benchmark recommendation hygiene, edit JSON/rollback safety, and capsule validation-trust fixes are released and publicly dogfooded.
Current release facts:
8143ccb chore(release): v1.9.2 [skip ci]faf67ed fix: harden edit JSON and capsule validation trust95bfd81 feat: add actionable agent context capsulefix: harden edit JSON and capsule validation trust merged and releasedfix: harden agent capsule trust alignment merged and releasedfeat: add actionable agent context capsule merged and releasede2bd7c2 fix: scope GPU probing and benchmark launcher warningsfix: scope GPU probing and benchmark launcher warnings merged and released as v1.8.33ab2635a fix: expose launcher route observability015fad9 fix: harden public launcher and agent contractse6d09a5 fix: preserve quoted patterns in Windows cmd shimf311469 docs: define agent context capsule roadmapdocs: define agent context capsule roadmap merged; Main CI run 25561521904 passed, CodeQL/dynamic main run 25561520180 passed, and semantic-release correctly skipped publishing.25609611007 passed through semantic-release, PyPI artifact validation, publish-github-release-assets, publish-pypi, and publish-success-gate; CodeQL run 25609610737 passedtensor-grep==1.9.2v1.9.2 include native CPU front doors, checksums, winget manifest, Homebrew formula, and publish instructionstg update from v1.9.1 installed sidecar tensor-grep==1.9.2, refreshed ~/.tensor-grep/bin/tg.exe, and verified tg 1.9.2. Profiled PowerShell, cmd, pwsh -NoProfile, WSL, Git Bash, and direct managed native tg.exe resolve tg 1.9.2; tg doctor --json reports version = 1.9.2, rust_binary_version_status = matches, search_acceleration_backend = standalone-native-tg, path_tg_first_launcher_kind = cmd-shim, fresh_shell_path_tg_first_launcher_kind = managed-native, and a path_tg_launcher_warning for current shells that still route through the compatibility shim before fresh-shell PATH. Public readiness passed 15/16 before this follow-up, failing only docs claim hygiene.scripts/install.ps1 for v1.8.31 put C:\Users\oimir\.tensor-grep\bin ahead of compatibility shim directories on User PATH. A simulated fresh shell resolves C:\Users\oimir\.tensor-grep\bin\tg.exe before C:\Users\oimir\bin\tg.cmd.tg search --multiline, tg search -U, tg search --files, tg search --null, tg run -r, and tg classify --format json all accept the advertised public shape on the installed front door.cmd /c tg, direct managed tg.cmd, native tg.exe, and Python subprocess.run([...]) all return exit 1 with empty stdout for fresh quoted no-match phrases.python scripts/agent_readiness.py --output artifacts/agent_readiness_agent_capsule.json passed all checks.TG_NATIVE_TG_BINARY or TG_MCP_TG_BINARY explicitly pins onedocs/SESSION_HANDOFF.mdCurrent product read:
rg remains the benchmark for raw cold exact-text search.ast-grep remains the structural-search feature/performance baseline; tg run is a validated useful slice, not full ast-grep equivalence.tg is strongest as agent-native code intelligence: scoped search, JSON/NDJSON, repo maps, defs, source, refs, callers, context bundles, blast-radius, AST search, rewrite planning, GPU inventory, and MCP.tg search --files, tg search --multiline / -U, tg search --null, tg run -r, tg classify --format json, Windows .cmd quoted multi-word no-match patterns, native-first Windows PATH ordering for fresh managed shells, and launcher-route observability for current-process versus fresh-shell PATH drift.cmd.exe, direct tg.cmd, and Python subprocess.run([...]) is a public Windows launcher contract. A split pattern can become a shorter false-positive search plus bogus paths, so keep public-windows-launcher-quoted-patterns in the fast agent-readiness gate.TG_SIDECAR_PYTHON and TG_NATIVE_TG_BINARY. Installer changes should preserve the staged replacement contract so a failed install cannot break an existing public shim, including checking native installer command exit codes before the staged swap. On Windows, the managed native front-door directory should be ahead of compatibility .cmd shim directories on PATH so cmd, unprofiled PowerShell, and Python subprocess calls resolve ~/.tensor-grep/bin/tg.exe before the slower argv-safe bridge. tg upgrade must verify the sidecar import/version before claiming success, including the scheduled Windows self-upgrade path, and managed native front doors must be refreshed when the verified sidecar version moves ahead of tg.exe.tg doctor --json is the first check for launcher drift. Inspect path_tg_first_launcher_kind, fresh_shell_path_tg_first_launcher_kind, and path_tg_launcher_warning before trusting Windows benchmark timings; existing shells can retain the slower compatibility shim even after fresh User PATH resolves the native front door.environment.tg_launcher_mode for the experiment and environment.tg_launcher_command_kind to distinguish native-exe, .cmd shim, uv, and Python-module routes. Treat benchmark warnings about shim/interpreter overhead as blocking for performance comparisons.--gpu-device-ids routing should only probe selected CUDA ordinals. Selecting GPU 0 must not initialize or warn about unrelated unsupported devices such as GPU 1.rg and tg_cpu at required scale. Unsupported-device inventory warnings should stay top-level or on the unsupported device row, not on unrelated selected-GPU timing rows.--format rg --sort path is the deterministic rg-shaped stdout contract. Token-saving output work should be a separate opt-in agent profile, not a mutation of raw rg/json/ndjson contracts.tg agent / Actionable Context Capsule is the product wedge: an opt-in workflow packet with primary file/function, route rationale, bounded snippets with line maps, validation evidence, edit order, checkpoint/rollback metadata, omission counts, confidence, call-site evidence status, and an "ask user before editing" recommendation when evidence is weak. Capsule v1 leaves related_call_sites empty unless verified call-site evidence is explicitly collected. Evidence labels should distinguish parser-backed, rg-backed, graph-derived, heuristic, LSP-confirmed, and stale/uncertain conclusions.confidence.overall and primary_target.confidence, expose query_language_hints, primary_target_language, validation_alignment, and validation_filtered_count, and require ask-before-editing.context-render / MCP context output must keep edit_plan_seed.primary_file, navigation_pack.primary_target.file, selected files/sources, and follow-up reads consistent. Check context_consistency when debugging agent handoff quality.tg ast-info --json exposes AST language identifiers for agents without help-text scraping.classify is local and deterministic by default. Use TENSOR_GREP_CLASSIFY_PROVIDER=cybert only when intentionally probing the CyBERT/Triton provider path, and keep provider failures quiet/fast for agent loops.edit-plan and context-render JSON should both expose top-level validation_commands; use that field first before inspecting nested navigation_pack or edit_plan_seed.tg search --files --hidden scans and no-ignore/unrestricted fallback scans through generated/cache/dependency directories are refused unless bounded with --glob, --type, or --max-depth, or explicitly opted in with --allow-broad-generated-scan. Use scoped paths, globs, file types, and --max-depth for tg search before reaching for opt-in. --max-repo-files, --max-callers, and --max-files are code-intelligence command budgets, not tg search flags.Known current weak spots:
tg search --files ... over generated artifact trees can still be expensive; the managed Windows launchers and Python path-list output should force UTF-8, but scope file-list commands to the smallest useful root.pwsh -NoProfile, and cmd. Old tensor-grep-owned Python*\Scripts\tg.exe launchers should now be removed or uninstalled by the Windows installer; any recurrence is release-regression evidence.wsl bash -lc 'tg --version' after shim changes.tg or tg.ps1 for regex metacharacters. Direct tg.cmd invocation with unescaped | is parsed by cmd.exe before the batch file receives argv.tg --version is one-line by default for scripts; use tg --version --verbose for feature/SIMD/Arrow details.Usage: tg, not Usage: python -m tensor_grep.impact --symbol can be noisier than blast-radius; use blast-radius for direct symbol impact.validation_commands can be heuristic and should be treated as hints.validation_plan[] rows should include detection (detected, heuristic, or generic). JavaScript package-manager commands require package.json evidence; Python commands require tests, project markers, or Python layout evidence; when no runner evidence exists, emit no command rather than a fake npm test or uv run pytest.validation_alignment reports filtered mismatches; do not silently pair a TypeScript primary target with pytest-only validation or a Python primary target with JS-only validation.uv run tg doctor --json should report them under skipped_native_tg_binaries, set rust_binary_version_status = stale-skipped, and keep searches on the Rust extension or Python path unless TG_NATIVE_TG_BINARY explicitly pins a standalone binary.--sort path for deterministic path ordering and --format rg for exact ripgrep-style text formatting. Sorted files-with-matches, files-without-match, and replacement output are regression-covered rg parity edges.tg upgrade must not trust stale package metadata immediately after publish and must not delete a working managed install before the replacement environment and front-door files have installed successfully. PowerShell native installer steps must check $LASTEXITCODE before the staged swap. tg upgrade must skip yanked PyPI releases, must not report "latest PyPI version" from unchanged local metadata without post-upgrade import/version verification, and must refresh or schedule refresh of the managed native front door when the sidecar package version changes. A PyPI-only publish is not enough when installers point at GitHub assets; release assets must be uploaded and verified first.A branch push or open PR starts PR CI only. It is not a release, not a released version, and not complete release state.
Release versioning starts only after a release-bearing PR is squash-merged to main, because semantic-release reads the final main commit subject.
A release-bearing PR is complete only after PR CI passes, the PR is squash-merged to main, main CI and semantic-release complete successfully, the release commit and tag exist on origin/main, publish-success-gate passes, git fetch origin main --tags is run, agents fast-forward local main to the release commit, and PyPI/public installer availability is verified.
Do not report final version state before the GitHub release, PyPI/package publish status, public install/update path, and local checkout have all been verified.
Confirm command resolution and version before trusting behavior:
Get-Command tg -ErrorAction SilentlyContinue | Format-List Source,CommandType,Version
Get-Command tg -All -ErrorAction SilentlyContinue | Format-Table -AutoSize CommandType,Source,Version
Get-Alias tg -ErrorAction SilentlyContinue | Format-List Definition,ResolvedCommandName
tg --version
cmd /c tg --version
pwsh -NoProfile -Command "tg --version"
where.exe tg
uv run tg doctor --json
Use scoped tg discovery first:
tg search --fixed-strings "<query>" src tests docs README.md
tg search --json "<query>" src tests docs
tg search --ndjson "<query>" src tests docs
Avoid broad generated-root file lists unless the task needs them:
tg search --files "AGENTS.md" . --hidden
Use one of these instead for agent-safe file discovery:
tg search --files src --hidden
tg search --files . --hidden --glob "*.py"
tg search --files . --hidden --max-depth 3
Only pass --allow-broad-generated-scan when the generated/cache/dependency tree walk is intentional.
| Task | Command |
|---|---|
| Basic search | tg "pattern" [path] |
| Explicit search | tg search "pattern" src tests docs |
| Fixed string | tg -F "literal.string" src |
| Context lines | tg -C 3 "pattern" src |
| JSON aggregate | tg search --json "pattern" src |
| NDJSON stream | tg search --ndjson "pattern" src tests docs |
| Files with matches | tg search "pattern" src --files-with-matches |
| AST search | tg run --lang python 'def $NAME($$$ARGS): $$$BODY' src --json |
| AST language identifiers | tg ast-info --json |
| Source lookup | tg source src --symbol someSymbol --json |
| Refs lookup | tg refs src --symbol someSymbol --json |
| Blast radius | tg blast-radius src --symbol someSymbol --json |
| Context bundle | tg context-render src --query "how routing works" --render-profile llm --json |
| Device inventory | tg devices --json |
| MCP server | tg mcp |
PowerShell expands $NAME and $$$ARGS inside double quotes. Use single quotes for AST metavariable patterns.
Start the server with:
tg mcp
Useful MCP tools include:
tg_mcp_capabilitiestg_searchtg_ast_searchtg_classify_logstg_devicestg_index_searchtg_rewrite_plantg_rewrite_applytg_rewrite_difftg_agent_capsuleCall tg_mcp_capabilities first in PyPI wheels, sandboxes, and agent hosts so the client knows whether a standalone native tg binary is available.
For code changes, follow AGENTS.md and run:
uv run ruff check .
uv run ruff format --check --preview .
uv run mypy src/tensor_grep
uv run pytest -q
For fast agent-readiness dogfood before push, run:
python scripts/agent_readiness.py --output artifacts/agent_readiness.json
This gate checks public shell version resolution, public-windows-launcher-quoted-patterns, repo doctor sanity, context_consistency, agent-capsule, agent-capsule-mixed-language, deterministic rg edge parity, broad generated-root scan guardrails, AST smoke, MCP context-render smoke, docs claim hygiene, current v1.9.2 positioning, and the managed native-upgrade contract. It does not replace the full validation gate.
For hot-path or benchmark-relevant changes, run the matching benchmark before updating claims:
python benchmarks/run_benchmarks.py --output artifacts/bench_run_benchmarks.json
python benchmarks/check_regression.py --baseline auto --current artifacts/bench_run_benchmarks.json
python benchmarks/run_hot_query_benchmarks.py --output artifacts/bench_hot_query_benchmarks.json
python benchmarks/run_ast_benchmarks.py --output artifacts/bench_run_ast_benchmarks.json
python benchmarks/run_ast_workflow_benchmarks.py --output artifacts/bench_run_ast_workflow_benchmarks.json
python benchmarks/run_gpu_benchmarks.py --output artifacts/bench_run_gpu_benchmarks.json
GPU benchmark SKIP is valid infrastructure state when dependencies such as Torch, cuDF, CUDA, or Triton are unavailable. Do not convert a skip into a speed claim.
| Mistake | Correction |
|---|---|
Claiming tg is always faster than rg | Keep rg as the cold exact-text benchmark; position tg as agent-native code intelligence with a validated compatibility set. |
Searching with rg by habit inside this repo | Use tg search first, then rg for parity or fallback. |
| Running broad generated-root scans | Scope the path, use --glob / --type / --max-depth, or opt in with --allow-broad-generated-scan only when the generated-tree walk is intentional. |
| Saving tokens by changing raw search contracts | Add an opt-in bounded agent formatter/profile; leave --format rg, --json, and --ndjson stable. |
| Trusting stale native diagnostics | Check uv run tg doctor --json; stale in-tree binaries should be stale-skipped, not selected implicitly. Rebuild or pin TG_NATIVE_TG_BINARY to opt in. |
| Trusting invented validation commands | Check validation_plan[].detection; package-manager commands require package.json, Python commands require Python/test/project evidence, and absent evidence should mean no command. |
| Claiming GPU wins from device detection | Run the GPU benchmark and record the accepted artifact. |
| Updating docs from memory | Update docs only from repo evidence, CI evidence, or benchmark artifacts. |
| Code | Meaning |
|---|---|
| 0 | Matches found or command succeeded |
| 1 | No matches found |
| 2 | Error occurred |