# WhyType

> Extracts the TypeScript compiler's own reasoning: diagnostics as "because"
> chains, generic type-parameter inference bindings, and conditional-type
> traces with real checker verdicts. Runs on the project's own typescript
> install (>=5.0 <7).

## For agents

- Setup: `npm i -D whytype && npx whytype init` — writes .mcp.json (Claude
  Code), .cursor/mcp.json when the repo uses Cursor, and an instruction block
  into an existing CLAUDE.md/AGENTS.md; `--hooks` adds a Claude Code
  PostToolUse check that reports new errors after every edit. Idempotent.
- MCP server: `npx whytype mcp` (stdio). Tools: whytype_diagnostics (compact
  error list; errorsOnly/offset/limit params; `project` targets a monorepo
  package's tsconfig), whytype_explain (full reasoning at file:line:col; also
  takes `project`), whytype_snippet (explain pasted code, no project needed).
- Claude Code manual route: `claude mcp add whytype -- npx whytype mcp` (run
  in the project being debugged; it needs a local `typescript` install).
- CLI: `npx whytype <file>:<line>:<col>` | `npx whytype check` |
  `--json` for stable structured output. Exit codes: 0 clean, 1 errors, 2 usage.
- Returns are markdown: `## error TS<code> — file:line:col`, a code frame, a
  `Because:` bullet chain (one bullet per elaboration step, nested), and a
  `Related:` list with declaration sites.

## What whytype_explain returns (verbatim sample)

## error TS2322 — src/main.ts:14:14

Type '{ port: string; host: string; }' is not assignable to type 'Config'.

Because:
- TS2326 Types of property 'port' are incompatible.
  - TS2322 Type 'string' is not assignable to type 'number'.

**`narrowed`** : `Config`

_typescript 6.0.3_

(The full return also carries a `>`-marked code frame around line 14, omitted
here for brevity. Cross-file causes arrive as `Related: src/shapes.ts:2:3 —
The expected type comes from property 'port' which is declared here on type
'Config'.`)

## Docs

- https://whytype.dev/docs/
- https://whytype.dev/ (in-browser playground, code never leaves the tab)
- https://github.com/zeelib1/whytype
- https://www.npmjs.com/package/whytype