debug-claude-session — Claude Code skill: what it does, how to install
debug-claude-session investigates Claude Code sessions by correlating local transcripts with cloud router logs via timestamps and models. Helps spot wire translation glitches when client rendering breaks.
Apache-2.0 ★ 5,622 updated 2026-10-29
npx skills add weave-os/router --skill debug-claude-session -a claude-codeWhat debug-claude-session does
This skill troubleshoots response rendering issues in Claude Code sessions routed through weave-os/router. It uses the session ID to locate the local transcript at ~/.claude/projects/...jsonl. The tool inspects assistant blocks, groups streamed turns by message.id, and decodes internal fields like provider signatures.
Local transcripts often lack request identifiers. Because of that, the skill correlates events against structured cloud logs using a tight UTC timestamp window and the reported message.model. Once the entries match, you can trace discrepancies between upstream responses and rendered output back to translation handlers in internal/translate.
Querying cloud logs requires .claude/skills/debug-claude-session/.deployment.json with your cloud provider and service settings. If this file is missing, the agent asks for deployment details interactively.
What it helps with
- locate local
.jsonlsession transcripts by ID - reconstruct streamed assistant blocks sharing the same
message.id - decode base64 provider signatures and embedded IDs
- match local client timestamps with upstream router cloud logs
Example prompts for the agent
- Investigate session b41a9e7f and find out why the thinking block rendered empty
- Locate transcript for session 8c2d1b and match it against GCP router logs
- Check session a192c4f to see which upstream model served the request
How to install debug-claude-session
1Skills CLI (Vercel)
npx skills add weave-os/router --skill debug-claude-session -a claude-code2Manually: put the files in place
~/.claude/skills/debug-claude-session/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debug-claude-session/
1Skills CLI (Vercel)
npx skills add weave-os/router --skill debug-claude-session -a codex2Manually: put the files in place
.agents/skills/debug-claude-session/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add weave-os/router --skill debug-claude-session -a cursor2Manually: put the files in place
.cursor/skills/debug-claude-session/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install weave-os/router .agents/skills/debug-claude-session2Manually: put the files in place
.github/skills/debug-claude-session/SKILL.md1Skills CLI (Vercel)
npx skills add weave-os/router --skill debug-claude-session -a gemini-cli2Platform CLI
gemini skills install https://github.com/weave-os/router --path .agents/skills/debug-claude-sessionManually: put the files in place
.devin/skills/debug-claude-session/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about debug-claude-session
How to install debug-claude-session in Claude Code?
Run npx skills add weave-os/router --skill debug-claude-session -a claude-code. This downloads the skill and places it into ~/.claude/skills/debug-claude-session/SKILL.md.
What does debug-claude-session do?
It correlates what the client rendered in the local .jsonl file with what upstream sent according to router cloud logs. This lets you pinpoint translation bugs in internal/translate.
Why are sessions correlated by time instead of request ID?
Claude Code local transcripts frequently omit request IDs. The skill pairs events by matching the UTC timestamp window alongside the specific message.model recorded in the transcript.
Source text
SKILL.md · Apache-2.0
---
name: debug-claude-session
description: Investigate a specific Claude Code session by session ID — correlate the local transcript (`~/.claude/projects/...jsonl`) with the router's production logs to understand what the client rendered vs. what the upstream served. Use when given a session ID and asked "why did X render?" for a Claude Code conversation routed through the router.
---
# 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:
```bash
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
```bash
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.):
```bash
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:
```bash
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).
### 5. Fetch cloud logs for the matching UTC window
Extract the timestamp range from the transcript:
```bash
python3 - <<'EOF'
import json
with open("<path>/<SESSION_ID>.jsonl") as f:
lines = [json.loads(line) for line in f if json.loads(line).get("timestamp")]
if lines:
print(f"UTC window: {lines[0]['timestamp']} to {lines[-1]['timestamp']}")
EOF
```
Then use your cloud logging tool with the config from `.deployment.json`:
```bash
# Example for gcloud/GCP. Adapt to your cloud provider:
gcloud logging read \
'resource.type="cloud_run_revision" AND resource.labels.service_name="router" AND timestamp>="2026-06-10T01:02:00Z" AND timestamp<="2026-06-10T01:08:00Z"' \
--project <project_id> --limit 20 --format=json \
> /tmp/cloud_logs.json
```
Filter for the served model to narrow results:
```bash
python3 - <<'EOF'
import json
with open("/tmp/cloud_logs.json") as f:
for entry in json.load(f):
payload = entry.get("jsonPayload", {})
# Adapt filter to your log schema:
if payload.get("decision_model") == "gpt-5.5":
print(json.dumps({
"timestamp": entry.get("timestamp"),
"message": payload.get("message"),
"decision_model": payload.get("decision_model"),
"decision_provider": payload.get("decision_provider"),
"stop_reason": payload.get("resp_stop_reason")
}))
EOF
```
### 6. Correlate transcript + cloud logs
Match entries from steps 2 and 5 by:
- **Timestamp** (transcript `timestamp` ≈ cloud log `timestamp` within ~1-2 seconds).
- **Model** (transcript `message.model` == cloud log `decision_model`).
Once matched, the cloud log entry tells you:
- **Which model/provider actually served** the turn (proof that the transcript came from that upstream).
- **How the turn was reconciled** (e.g. `stop_reason` demotions, tool_use handling, usage accounting).
### 7. Trace to the translation code
Now that you've identified the model/provider path (step 4) and confirmed it in cloud logs (step 6), open the relevant translation file in `internal/translate/`:
- `responses_to_anthropic_writer.go` — OpenAI Responses API.
- `stream.go` + `emit_anthropic.go` — OpenAI-compatible chat.
- `gemini_stream.go` + `emit_gemini.go` — Google Generative Language.
- `emit_anthropic.go` — Anthropic passthrough (mostly copy).
Find the emitter function that produces the block shape you're seeing:
- `emitContentBlockStartThinking`, `emitContentBlockDeltaThinking` — thinking blocks.
- `emitContentBlockStartTool`, `emitContentBlockDeltaTool` — tool_use blocks.
- Similar for text, tool_result, etc.
Read backward from the emitter to the upstream event that triggered it. This is where the "why" lives.
## Example: Empty thinking block
1. Local transcript shows: `thinking: ""` but `signature: "<1500 chars>"` (step 3).
2. Cloud log shows: `decision_model=gpt-5.5, decision_provider=openai, stop_reason=tool_use` (step 5-6).
3. Translation path: OpenAI Responses → `responses_to_anthropic_writer.go` (step 4).
4. Trace upstream event: `response.reasoning_summary_text.delta` with empty delta but populated item on `response.output_item.added` (step 7).
5. Emitter: `handleReasoningDelta` → `emitContentBlockDeltaThinking("", ...)` which does nothing (empty delta skipped), but the thinking block was already opened by `handleOutputItemAdded` (line 279).
6. Root cause: OpenAI returned a reasoning item with `encrypted_content` but under `reasoning.summary:"auto"`, no summary text. The block can't be skipped because the signature must round-trip to the next turn.
## Notes
- The transcript records the **post-translation** Anthropic Messages shape — it never shows raw upstream Responses/Gemini events. Reconstruct upstream behavior by reading the emitter code + cloud logs together.
- `message.id` groups lines from the same logical turn; reconstruct the full turn by collecting all lines sharing an `id`.
- If the cloud log query returns nothing or the wrong model, expand the UTC window or check the model name spelling.
- To reproduce a translation artifact locally (without prod), use the sibling `test-claude-locally` skill to run the router with a mock upstream emitting the exact wire shape you're investigating.
© weave-os · Apache-2.0 · weave-os/router