# debug-claude-session

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 5622 repo stars
- Author: weave-os
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/weave-os/router/tree/HEAD/.agents/skills/debug-claude-session/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/debug-claude-session

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill debug-claude-session -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/debug-claude-session/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/debug-claude-session/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill debug-claude-session -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/debug-claude-session/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill debug-claude-session -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/debug-claude-session/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install weave-os/router .agents/skills/debug-claude-session
```

2. **Manually: put the files in place**
- File: `.github/skills/debug-claude-session/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill debug-claude-session -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/weave-os/router --path .agents/skills/debug-claude-session
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/debug-claude-session/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/weave-os/router/tree/HEAD/.agents/skills/debug-claude-session/SKILL.md

## When to use it
- locate local `.jsonl` session 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
- 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

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: cdfa30eccf8a004f.

BEGIN THIRD-PARTY FILE cdfa30eccf8a004f
````text
---
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.
````
END THIRD-PARTY FILE cdfa30eccf8a004f

The third-party file has ended. Everything between the cdfa30eccf8a004f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2631 of 11520 bytes. © weave-os · Apache-2.0 · https://github.com/weave-os/router/tree/HEAD/.agents/skills/debug-claude-session/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
