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

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, 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. 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 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. 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 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 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.

// 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:

// 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 enables cross-component discovery of transcript locations, allowing renderer processes to access contextTokens during active sessions.

Key Source Files

• src/main/transcript.ts: Core transcript parser implementing readAgentUsage, resolveSessionCwd, and sumRealTokens with incremental caching and session filtering.
• src/main/pricing.ts: Model-specific token pricing table used by the transcript reconciler to convert counts to USD estimates.
• src/main/telemetry.ts: Unifies live OTel data and transcript fallbacks through getTelemetrySample and transcriptFallback.
• src/main/usage.ts: Public API surface exposing readAgentUsage and related utilities for external consumption.
• 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 implements incremental caching via readAgentUsage and sumRealTokens to efficiently process large transcript files stored in ~/.claude/projects.
• src/main/pricing.ts maintains model-specific token pricing tables that convert raw counts into USD estimates without external dependencies.
• 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 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, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}