# How the Transcript Reading System Provides Real Token and Cost Telemetry in Munder Difflin

> Discover how Munder Difflin's transcript reading system offers real token and cost telemetry. Learn how it parses Claude Code transcripts for valuable insights when live data is unavailable.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: internals
- Published: 2026-08-20

---

**The transcript reading system in Munder Difflin provides real token and cost telemetry by parsing Claude Code transcript files from disk when live OpenTelemetry data is unavailable, using an incremental caching mechanism to compute token totals and USD costs via model-specific pricing tables.**

Munder Difflin implements a hybrid telemetry architecture that ensures accurate billing visibility even when live monitoring fails. The **transcript reading system** serves as a critical fallback mechanism that parses JSONL transcript files stored in `~/.claude/projects`, reconciling token usage against predefined pricing tables to deliver real-time cost estimates. This approach guarantees that developers always have access to consumption metrics regardless of their OpenTelemetry configuration.

## Two-Layer Telemetry Architecture

Munder Difflin employs a hybrid approach that prioritizes real-time monitoring while ensuring offline reliability through transcript parsing.

**Live OpenTelemetry Stream**: As implemented in [`src/main/telemetry.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/telemetry.ts), the primary layer collects token counts directly from running Claude Code processes via the OTel collector, providing millisecond-accurate usage data.

**Transcript File Fallback**: When OTel is disabled or unreachable, the system activates the transcript reading system defined in [`src/main/transcript.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/transcript.ts). This fallback parses JSONL transcript files stored in `~/.claude/projects` to reconstruct token usage and calculate costs retroactively.

## Core Implementation Components

### Transcript Parser with Incremental Caching

The `readAgentUsage` function in [`src/main/transcript.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/transcript.ts) serves as the entry point for the fallback mechanism. It resolves the working directory via `resolveSessionCwd` and maintains an incremental cache (`cachedTotals`) to avoid re-parsing multi-megabyte JSONL files on every read. The parser extracts `input_tokens` and `output_tokens` from each line, filtering optionally by `sessionId` through the `sumRealTokens` utility.

### Model Pricing Lookup

Token counts convert to USD estimates through the pricing table defined in [`src/main/pricing.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pricing.ts). This module maps each Claude model identifier to its per-1k-token price, enabling the transcript reconciler to compute accurate costs without external API calls.

### Unified Telemetry Interface

The `getTelemetrySample` function in [`src/main/telemetry.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/telemetry.ts) orchestrates data sources, preferring live OTel metrics when available. When telemetry is disabled, it invokes the transcript fallback via `transcriptFallback(agentId)`, merging results to prevent double-counting while returning a standardized `AgentUsageSample` structure.

## How the Transcript Reading System Processes Files

The fallback mechanism follows a deterministic five-step sequence to reconstruct usage metrics from Claude Code transcripts:

1. **Directory Resolution**: `resolveSessionCwd` locates the transcript directory for a given working directory, typically resolving to `~/.claude/projects/<hash>`.
2. **Incremental Parsing**: `readAgentUsage` opens the latest `.jsonl` files and updates the `cachedTotals` map, ensuring repeated reads remain performant even with large log files.
3. **Token Aggregation**: `sumRealTokens` walks all transcript files for the specified cwd, summing token fields across JSON lines and applying optional `sessionId` filters.
4. **Cost Calculation**: The total token count multiplies against `modelPricing[modelId]` from [`src/main/pricing.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pricing.ts) to derive the USD estimate.
5. **Result Exposure**: The function returns an `AgentUsageSample` object containing `tokens`, `usd`, `modelId`, and `sessionId` fields.

## Working with the Telemetry API

Access real-time usage data through the unified interface regardless of which telemetry layer is active. The system automatically prefers live OTel data when available.

```typescript
// Fetch combined telemetry using the preferred live source with transcript fallback
import { getTelemetrySample } from '@/main/telemetry';

const usage = await getTelemetrySample(agentId);
console.log(`Tokens: ${usage.tokens}, Cost: $${usage.usd}`);

```

For direct transcript parsing without OTel integration, use the public API exposed in [`src/main/usage.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/usage.ts):

```typescript
// Direct transcript fallback for CLI tools or offline analysis
import { readAgentUsage } from '@/main/transcript';

const sample = readAgentUsage('/path/to/project');
if (sample) {
  console.log(`Model: ${sample.modelId}`);
  console.log(`Total tokens: ${sample.tokens}`);
  console.log(`Estimated cost: $${sample.usd}`);
}

```

Registration with the Hive registry in [`src/main/index.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/index.ts) enables cross-component discovery of transcript locations, allowing renderer processes to access `contextTokens` during active sessions.

## Key Source Files

- **[`src/main/transcript.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/transcript.ts)**: Core transcript parser implementing `readAgentUsage`, `resolveSessionCwd`, and `sumRealTokens` with incremental caching and session filtering.
- **[`src/main/pricing.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pricing.ts)**: Model-specific token pricing table used by the transcript reconciler to convert counts to USD estimates.
- **[`src/main/telemetry.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/telemetry.ts)**: Unifies live OTel data and transcript fallbacks through `getTelemetrySample` and `transcriptFallback`.
- **[`src/main/usage.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/usage.ts)**: Public API surface exposing `readAgentUsage` and related utilities for external consumption.
- **[`src/main/index.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/index.ts)**: Registers the transcript resolver with the Hive registry to enable cross-component transcript discovery.

## Summary

- The **transcript reading system** provides reliable token and cost telemetry by parsing Claude Code JSONL files when live OpenTelemetry data is unavailable.
- **[`src/main/transcript.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/transcript.ts)** implements incremental caching via `readAgentUsage` and `sumRealTokens` to efficiently process large transcript files stored in `~/.claude/projects`.
- **[`src/main/pricing.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pricing.ts)** maintains model-specific token pricing tables that convert raw counts into USD estimates without external dependencies.
- **[`src/main/telemetry.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/telemetry.ts)** unifies live OTel streams and transcript fallbacks through `getTelemetrySample`, ensuring consistent `AgentUsageSample` structures across the application.
- The system registers transcript resolvers in [`src/main/index.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/index.ts) to enable Hive registry integration for UI components and agent management tools.

## Frequently Asked Questions

### Where does the transcript reading system locate Claude Code transcript files?

The system resolves transcript directories through `resolveSessionCwd` in [`src/main/transcript.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/transcript.ts), which maps working directories to the Claude Code projects folder at `~/.claude/projects/<hash>`. This path contains the JSONL transcript files that record all agent interactions and token consumption.

### How does Munder Difflin calculate costs from transcript data?

After aggregating token counts via `sumRealTokens`, the system multiplies the total against per-model pricing defined in [`src/main/pricing.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pricing.ts). This lookup table maps each `modelId` to its per-1k-token rate, enabling offline cost estimation without requiring live API access to pricing services.

### Can the transcript reading system filter usage by specific sessions?

Yes, the `readAgentUsage` function accepts optional `sessionId` parameters that `sumRealTokens` applies when walking transcript files. This filtering capability allows precise cost attribution for individual agent sessions even when multiple sessions share the same project directory.

### What prevents performance degradation when reading large transcript files?

The implementation maintains an incremental cache (`cachedTotals`) that stores parsed token totals per file. When `readAgentUsage` encounters previously processed transcripts, it retrieves cached values rather than re-parsing the entire JSONL stream, ensuring O(1) lookup complexity for unchanged files regardless of log size.