noctrace: Skill for Claude Code

Context Health Scoring Specification

Purpose

Compute a real-time A-F grade representing the health of a Claude Code session's context window. This warns developers when quality is degrading before they notice it in the output.

Input Data

All data comes from parsed JSONL records. The health scorer receives an array of parsed records (not raw lines) and computes the grade incrementally — it can be called after each new record to update the score.

interface HealthInput {
  assistantRecords: {
    timestamp: number;
    inputTokens: number;
    outputTokens: number;
  }[];
  compactionEvents: {
    timestamp: number;
    preTokens: number;
    trigger: "auto" | "manual";
  }[];
  toolCalls: {
    timestamp: number;
    toolName: string;
    filePath?: string; // for Read calls
    isError: boolean;
  }[];
  sessionStartTime: number;
  sessionEndTime: number | null; // null = still running
}

Signal Computations

1. Context Fill (weight: 40%)

function computeFillScore(input: HealthInput): number {
  const maxWindow = 200_000;
  // Use the most recent assistant record's input_tokens
  const latest = input.assistantRecords.at(-1);
  if (!latest) return 100; // no data = healthy
  const fillPct = latest.inputTokens / maxWindow;

  if (fillPct < 0.50) return 100;  // A
  if (fillPct < 0.65) return 80;   // B
  if (fillPct < 0.80) return 60;   // C
  if (fillPct < 0.90) return 40;   // D
  return 20;                        // F
}

2. Compaction Count (weight: 25%)

function computeCompactionScore(input: HealthInput): number {
  const count = input.compactionEvents.length;
  if (count === 0) return 100;  // A
  if (count === 1) return 75;   // B
  if (count === 2) return 55;   // C
  if (count === 3) return 35;   // D
  return 15;                     // F
}

3. Re-read Ratio (weight: 15%)

Track file paths from Read tool calls. A "re-read" is any Read call targeting a file path that was already read earlier in the session.