Claude Session Router Debugger

Debugging a Claude Code session

Given a Claude Code session ID, pull the local transcript (what the client saw) and the corresponding production cloud logs (which model/provider served it), then correlate them to understand the wire-format translation. The local .jsonl is ground truth for what rendered; the cloud logs confirm what the upstream sent; the internal/translate code explains why the wire shape looks that way.

Setup: Cloud deployment config

Before starting, create a gitignored config file with your deployment's cloud logging details:

cat > .claude/skills/debug-claude-session/.deployment.json <<'EOF'
{
  "cloud_provider": "gcp",
  "project_id": "your-project-id",
  "region": "us-central1",
  "service_name": "router",
  "log_command_template": "gcloud logging read ... --project {project_id} --format=json"
}
EOF
git add .claude/skills/debug-claude-session/.deployment.json.example
# .deployment.json itself should be gitignored

If .deployment.json is missing, the agent will prompt you for these details and walk you through creating it. The file is gitignored and contains no secrets — it's just the service/project/region names needed to construct cloud log queries.

Critical gotchas (read first)

• The transcript is the source of truth for rendering. What the client showed is exactly the assistant message.content blocks in the .jsonl — not what you assume the model emitted. Always inspect block contents (decode fields, check lengths) before concluding something is "empty" or "corrupt".
• Streaming splits one logical turn across multiple assistant lines. Each line may hold a single block; they share a message.id and message.model. Reconstruct the full turn by collecting all lines with the same message.id.
• Block content may carry encoded state. Fields like signature, id, and input often encode provider-specific state (e.g. encrypted reasoning). Decode and inspect before skipping or dismissing a block.
• Cloud logs are structured, not free text. Filter queries on specific JSON fields (e.g. jsonPayload.decision_model, jsonPayload.message). The exact field names depend on the router's logging schema — ask if unsure.
• Correlate by time + model, not request id. The local transcript has UTC timestamps (timestamp field); request IDs are often absent. Use a tight UTC window around transcript timestamps plus the served decision_model to find matching cloud log entries.

Workflow

- [ ] 1. Locate the local transcript
- [ ] 2. Extract the assistant blocks showing the symptom
- [ ] 3. Decode block internals (signatures, ids, sizes)
- [ ] 4. Identify model + provider from the transcript
- [ ] 5. Fetch cloud logs for the matching UTC window
- [ ] 6. Correlate transcript + cloud logs
- [ ] 7. Trace to the translation code in internal/translate

1. Locate the local transcript

find ~/.claude/projects -name '<SESSION_ID>*' -type f

You get <path>/<SESSION_ID>.jsonl (the transcript, one JSON object per line) and a sibling <SESSION_ID>/ directory (tool-output spillover). The .jsonl file is the ground truth. wc -l it — typical sessions are tens to hundreds of lines.

2. Extract the assistant blocks showing the symptom

Each line is a typed event. Scan for type: "assistant" entries. Each carries:

• message.id — groups lines from the same logical turn.
• message.model — the served model (e.g. gpt-5.5, claude-opus-4-8).
• message.stop_reason — how the turn ended (end_turn, tool_use, max_tokens).
• message.content[] — list of blocks (text, thinking, tool_use, tool_result).

Adapt this template to search for your symptom (empty blocks, missing content, unexpected stop_reason, etc.):

python3 - <<'EOF'
import json
with open("<path>/<SESSION_ID>.jsonl") as f:
    for i, line in enumerate(f):
        try:
            o = json.loads(line)
        except:
            continue
        if o.get("type") != "assistant":
            continue
        msg = o.get("message", {})
        # Adapt this filter to your symptom:
        for block in msg.get("content", []):
            if isinstance(block, dict) and block.get("type") == "thinking":
                thinking_text = block.get("thinking", "")
                signature = block.get("signature", "")
                if thinking_text == "":  # Your condition here
                    print(f"line {i+1}: model={msg.get('model')} "
                          f"stop_reason={msg.get('stop_reason')} "
                          f"thinking_len={len(thinking_text)} "
                          f"signature_len={len(signature)}")
EOF

Print model, stop_reason, block type/length — enough to see the pattern at a glance.

3. Decode block internals

Don't assume a short or empty field is meaningless. Many blocks carry encoded provider state. Inspect the actual bytes:

python3 - <<'EOF'
import json, base64
line_num = <LINE>  # From step 2
with open("<path>/<SESSION_ID>.jsonl") as f:
    o = json.loads(f.readlines()[line_num - 1])
for block in o["message"].get("content", []):
    block_type = block.get("type")
    print(f"=== {block_type} ===")
    # Print all fields and their lengths:
    for key, val in block.items():
        if isinstance(val, str):
            print(f"  {key}: len={len(val)} head={val[:80]!r}")
        else:
            print(f"  {key}: {type(val).__name__} {val!r}")
    # If any field looks base64-encoded, try decoding:
    if "signature" in block and block["signature"]:
        try:
            decoded = base64.b64decode(block["signature"])
            print(f"  signature (decoded): {decoded[:160]!r}")
        except Exception as e:
            print(f"  signature (decode failed): {e}")
EOF

This reveals what's actually inside. Look for:

• Encrypted state (e.g. encrypted_content, enc fields) that must round-trip to the upstream.
• Embedded IDs (e.g. OpenAI reasoning signatures embedded in tool_use.id).
• Redundant carriers — the same state might be duplicated across blocks.

4. Identify model + provider from the transcript

From the message.model field (step 2), note the served model. This tells you:

• Which upstream (e.g. gpt-* → OpenAI, claude-* → Anthropic, gemini-* → Google).
• Which translation code handles it (e.g. gpt-* Responses → internal/translate/responses_to_anthropic_writer.go).

Also note message.id (ids are unique per response; the prefix marks the path):

• msg_responses_* → OpenAI Responses API path (streaming).
• msg_translated_* → OpenAI chat-completions path (router-generated id; upstream-provided ids pass through unchanged).
• msg_01... (Anthropic-native id) → Anthropic Messages path (passthrough).