TypeScript Error Fixer

Fix all TypeScript compilation errors systematically using a 4-phase workflow. Zero tolerance for

any

types.

Phase 1: Discovery

1. Detect the package manager (check for

   package-lock.json

   ,

   yarn.lock

   ,

   bun.lockb

   ,

   pnpm-lock.yaml

   ).
2. Run the TypeScript compiler with a 1-2 minute timeout, redirecting output to a log file:

   tsgo --noEmit 2>&1 | tee tsc-<YYYY-MM-DD-HHmmss>.log
   

   Filter to specific directories:

   tsgo --noEmit | rg "src/"

3. Parse the log: extract every error with its file path, line number, error code, and message.
4. Group errors by file and produce a structured error report.

Phase 2: Planning

1. Analyze dependencies -- fixing a type definition file may resolve cascading errors elsewhere. Identify these first.
2. Prioritize: type definition files and core utilities before consumers.
3. Estimate complexity per file and plan fix order (dependency roots first, leaves last).

Phase 3: Subagent Deployment

For each file with errors, deploy a subagent (via the Agent tool):

• Identifier:

  ts-fix-<filename-without-extension>

• Context to provide:
  • The specific file path and all its errors (line numbers, codes, messages).
  • Relevant project patterns from CLAUDE.md.
  • Related type definitions the file depends on.
• Subagent instructions:
  1. Read the file and understand its purpose.
  2. Examine related files and type definitions.
  3. Research the root cause of each error.
  4. Apply proper type fixes (never use

     any

     -- see rules below).
  5. Verify the fix does not introduce new errors.

Phase 4: Verification

1. Re-run

   tsgo --noEmit

   (or filter:

   tsgo --noEmit | rg "src/"

   ).
2. Confirm all original errors are resolved.
3. Confirm no new errors were introduced.
4. Produce a summary report: files changed, errors fixed, types improved.

Zero Tolerance for

any

any

is never an acceptable fix. When you encounter it:

1. Research the actual type by examining:
   • Function signatures and return types
   • API response structures
   • Library type definitions (

     @types

     packages)
   • Runtime data flow and usage patterns
2. Use proper TypeScript utilities:

   • Partial<T>

     ,

     Pick<T, K>

     ,

     Omit<T, K>

     ,

     Record<K, V>

   • unknown

     with type guards instead of

     any

   • ReturnType<T>

     ,

     Parameters<T>

     for function-derived types
   • Create dedicated type/interface definitions for complex shapes
3. If

   any

   is temporarily unavoidable, add a

   // TODO:

   comment explaining why and the resolution path. This is the only exception.

Type Research Tools

Per-file checking (faster than full recompilation):

• tools mcp-tsc <file>

  -- persistent LSP server, ~100ms for incremental checks

• tools mcp-tsc --hover --line N --text symbol file.ts

  -- type introspection to find the correct type replacing

  any

Claude Code LSP operations (built-in):

• goToDefinition

  -- trace type origins to their source

• hover

  -- get inline type info for any symbol

• findReferences

  -- understand usage patterns across the codebase

Use these when researching actual types to replace

any

instead of guessing.

Error Handling

• If

  tsgo

  fails to run, check

  tsconfig.json

  for config issues first.
• If errors span >100 files, prioritize critical/shared files and process in batches.
• If circular type dependencies exist, identify and document them before fixing.

Quality Checklist

• Every type is properly researched, not guessed.
• Fixes align with project-specific patterns (check CLAUDE.md).
• Complex type decisions have explanatory comments.
• Typing patterns are consistent across the codebase.
• No

  any

  types remain (or each has a documented TODO with resolution path).