ts-inspect-cli AGENTS.md

ts-inspect: Semantic Type Information

When an agent needs compiler-derived TypeScript information, prefer the local read-only ts-inspect CLI over opening many source files, guessing types from call sites, or plain-text grep for semantic questions. It answers compiler-resolved questions through ts-morph and emits compact deterministic JSON to stdout. It never modifies source files.

How to run

npx ts-inspect <command> <symbol|location|file>

The ts-inspect bin also works directly when it is on PATH:

ts-inspect <command> <symbol|location|file>

Prefer npx ts-inspect for portability, since the bin may not be on PATH in every project.

The CLI loads the project from the repository's tsconfig.json (discovered by walking up from the current working directory), so all configured compilerOptions.paths aliases resolve correctly through ts-morph. No manual alias parsing is performed.

Command cheat-sheet

• Function parameters: npx ts-inspect params handleSubmit
• Resolved return type: npx ts-inspect return fetchUser
• Object/interface properties: npx ts-inspect properties UserConfig
• Type of a symbol: npx ts-inspect type getButtonStyle
• Type at a location: npx ts-inspect type src/path/to/file.ts:4:17
• Signatures (overloads preserved): npx ts-inspect signature getButtonStyle
• Declarations: npx ts-inspect definition generateSlug
• Precise snapshot at a location: npx ts-inspect at src/hooks/useAuth.ts:10:15
• Module imports: npx ts-inspect imports src/hooks/useAuth.ts
• Module exports: npx ts-inspect exports src/utils/format.ts

Location syntax

relative/path/to/file.ts:LINE:COLUMN (also .tsx / .mts / .cts). Line and column are 1-based. Example:

npx ts-inspect at src/hooks/useAuth.ts:10:15

Usage hierarchy

Need exact TypeScript type information?
	-> ts-inspect

Need function object parameters?
	-> ts-inspect params

Need the resolved return type?
	-> ts-inspect return

Need object/interface properties?
	-> ts-inspect properties

Need the type of a symbol or at a location?
	-> ts-inspect type

Need call signatures (overloads preserved)?
	-> ts-inspect signature

Need where a symbol is declared?
	-> ts-inspect definition

Know an exact file location?
	-> ts-inspect at FILE:LINE:COLUMN

Need the imports of a file?
	-> ts-inspect imports FILE

Need the exports of a file?
	-> ts-inspect exports FILE

Need an AST structural pattern?
	-> ast-grep, if installed

Need plain text/string search?
	-> ripgrep

Need compiler validation?
	-> tsc --noEmit

Need lint/style enforcement?
	-> ESLint