ts-query

name	ts-query
description	Semantic TypeScript queries (find references, dead exports, imports, diagnostics) using the compiler API. Use when finding all usages of a symbol, checking what imports an export, detecting dead code, listing exports, or checking for errors — especially during refactoring or cleanup work in a TypeScript monorepo.

ts-query — semantic TypeScript queries

Runs from repo root and queries the server/ package by default; file paths are relative to server/. To query another package (client/, shared/), run the script from inside that package — it resolves the nearest tsconfig.json at or above the current directory.

.agents/skills/ts-query/scripts/ts-query.mjs <command> <file> [symbol]

Commands

refs — find all references

ts-query.mjs refs src/shared/agent.ts AgentRunStatus

Prints file:line:col for every reference, including the definition. Handles re-exports and alias symbols correctly.

imports — find importing files

ts-query.mjs imports src/shared/realtime.ts EnvironmentEventPayload

Lists files that import the symbol. Faster than refs when you only need to know where it's used, not exactly which line.

dead — find unused exports

ts-query.mjs dead src/shared/agent.ts

Lists exports with zero external references. Caveat: exports consumed only through function signatures (return/parameter types) will be flagged — use human judgment.

exports — list all exports

ts-query.mjs exports src/server/agents/agentDiscovery.ts

Prints kind name file:line:col for every top-level export.

check — diagnostics

ts-query.mjs check src/server/agents/BaseAgent.ts

Shows syntactic + semantic TypeScript errors for a file. Prints "No errors." if clean.

When to use

Prefer this over rg/grep when you need:

• All references to a symbol (not just string matches)
• To know if an export is dead code
• To see what files depend on a module
• Semantic errors that tsc --noEmit catches but grep can't

For simple text searches, rg is faster. Use ts-query when you need the type checker's understanding of the code.

Batch dead-symbol scan

# Whole server/ package (the default)
.agents/skills/ts-query/scripts/find-all-dead.mjs

# Filter to a directory within the package
.agents/skills/ts-query/scripts/find-all-dead.mjs src/shared
.agents/skills/ts-query/scripts/find-all-dead.mjs src/server/agents

# Scan a different package: <dir-filter> <package-root>
.agents/skills/ts-query/scripts/find-all-dead.mjs src/lib ../../../../client

Scans every source file for exports with zero named imports and outputs file symbol for each. The first arg filters by directory prefix; an optional second arg points the scan at another package root (default server/).

False positives — investigate every result

The scanner only detects explicitly named imports. TypeScript can consume a type without ever naming it. Every result must be investigated — do not blindly delete. Check each candidate with refs to confirm:

ts-query.mjs refs <file> <symbol>

Known false-positive patterns (symbol will show zero refs but is still in use):

Pattern	Example	Why invisible
Union members	export type Foo = A | B — B is never imported by name	Consumers import Foo, not B
JSX prop interfaces	<Modal open /> — Props consumed through JSX	No import { ModalProps } anywhere
Return/param types	export function build(): Options	Callers get Options via type inference
Barrel re-exports	export type { X } from './src'	Consumers import X from original location
Tool config exports	export default defineConfig({...})	Vite/CLI reads it, not source files

Write findings to .var/dead_symbols.md and categorize each entry with a notes column explaining whether it's truly dead or a false positive.