cctypes

A comprehensive TypeScript types package for Claude Code hooks API, providing complete type definitions, runtime type guards, and discovery utilities for building type-safe Claude Code integrations.

Features

• Complete Type Coverage: TypeScript definitions for all Claude Code hooks and tools
• Runtime Type Guards: Validate data at runtime with generated type guard functions
• Transcript Discovery: Automatically discover and generate types from real Claude Code transcripts
• Multiple Module Formats: Supports ESM, CommonJS, and TypeScript declarations
• Comprehensive Testing: Full test coverage with both unit and type-level tests

Installation

npm install cctypes

Quick Start

Basic Usage

import { isPreToolUseInput, HookEventName } from 'cctypes';
import type { PreToolUseHookInput, BashInput } from 'cctypes/tools';

// Type-safe hook handling
function handleHook(input: unknown) {
  if (isPreToolUseInput(input)) {
    console.log(`About to use tool: ${input.tool_name}`);
    
    if (input.tool_name === 'bash') {
      const bashInput = input.tool_input as BashInput;
      console.log(`Command: ${bashInput.command}`);
    }
  }
}

// Type definitions
const hookEvent: HookEventName = 'PreToolUse';
const bashInput: BashInput = {
  command: 'npm test',
  timeout: 30000
};

Transcript Discovery

Discover and generate types from your actual Claude Code usage:

# Analyze all transcript files and generate types
npm run transcript:discover

# Analyze specific files with custom settings
npm run transcript:discover -- "./transcripts/*.jsonl" --min-occurrences 3 --verbose

# Validate existing types against real transcript data
npm run transcript:validate

The discovery system will:

• Analyze your JSONL transcript files
• Discover patterns in tool usage and hook events
• Generate accurate TypeScript types based on real data
• Validate existing type definitions
• Provide confidence scores and detailed reports

Example output:

=== Discovery Summary ===
Status: complete
Duration: 23s

Analysis Results:
  - Entries processed: 5,847
  - Unique tools: 8
  - Entry types: 12
  - Files processed: 15

Validation Results:
  - Valid: Yes
  - Errors: 0
  - Warnings: 2

Available Packages

Core Types

import type { 
  HookInput, 
  HookEventName, 
  PreToolUseHookInput,
  PostToolUseHookInput 
} from 'cctypes';

Tool Types

import type { 
  BashInput, 
  ReadInput, 
  WriteInput,
  ToolInputMap 
} from 'cctypes/tools';

Type Guards

import { 
  isHookInput,
  isPreToolUseInput,
  isPostToolUseInput 
} from 'cctypes/guards';

Transcript Types

import type { 
  TranscriptEntry, 
  ToolInvocationEntry,
  MessageEntry 
} from 'cctypes/transcript';

Discovery System

import { 
  DiscoveryEngine, 
  TranscriptAnalyzer 
} from 'cctypes/transcript/discovery';

Documentation

• Transcript Discovery Guide - Complete guide to analyzing transcript files and generating types
• Discovery API Reference - Detailed API documentation for the discovery system
• Hook Types Documentation - Reference for all hook event types and their schemas

NPM Scripts

Core Development

• npm run build - Build all targets (ESM, CommonJS, types, scripts)
• npm test - Run all tests
• npm run typecheck - TypeScript compilation check
• npm run lint - Run ESLint

Transcript Discovery

• npm run transcript:discover - Full discovery: analyze transcripts and generate types
• npm run transcript:validate - Validate existing types against transcript data
• npm run transcript:generate-types - Generate types only (no reports)
• npm run transcript:analyze - Detailed analysis with value patterns

Example Commands

# Basic transcript discovery
npm run transcript:discover

# Analyze specific transcript files
npm run transcript:discover -- file1.jsonl file2.json

# Custom analysis settings
npm run transcript:discover -- --min-occurrences 5 --max-depth 8 --verbose

# Output to custom directory
npm run transcript:discover -- --output-dir ./my-types --filename my-types.ts

# Validation only (no type generation)
npm run transcript:validate -- --existing-types-dir ./src/types

Project Structure

cctypes/
├── src/                    # Source code
│   ├── events/            # Hook event type definitions
│   ├── tools/             # Tool schema definitions
│   ├── guards/            # Type guard functions
│   ├── transcript/        # Transcript parsing and discovery
│   │   └── discovery/     # Discovery system implementation
│   └── __tests__/         # Test files
├── docs/                  # Documentation
│   ├── transcript-discovery.md  # Discovery system guide
│   └── api/              # API documentation
│       └── discovery.md  # Discovery API reference
├── scripts/               # Build and utility scripts
├── discovery-output/      # Discovery results (gitignored)
└── dist/                  # Build output
    ├── cjs/              # CommonJS build
    ├── esm/              # ES modules build
    └── types/            # TypeScript declarations

Discovery System Workflow

1. Collect Transcripts: Gather JSONL transcript files from Claude Code usage
2. Run Discovery: Analyze patterns in tool usage, hook events, and data structures
3. Generate Types: Create TypeScript definitions based on discovered patterns
4. Validate: Check compatibility with existing type definitions
5. Integrate: Use generated types in your Claude Code integrations

// Example: Using discovered types
import type { DiscoveredBashInput } from './discovery-output/discovered-types';

function executeBashCommand(input: DiscoveredBashInput) {
  // Type-safe with real-world patterns discovered from transcripts
  console.log(`Executing: ${input.command}`);
  if (input.timeout) {
    console.log(`Timeout: ${input.timeout}ms`);
  }
}

Contributing

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Run tests: npm test
5. Make your changes
6. Ensure tests pass and types are correct
7. Submit a pull request

License

MIT