# Claude Extension Logging

> Document how to capture the directional Claude extension/shim traffic so the renamed JSONL streams (`claude_*` and `claude_shim_*`) are always written and can be compared against Codex logs.

- Skill: `tankygranny05/claude-extension-logging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/claude-extension-logging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/claude-extension-logging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tankygranny05 (https://skillmd.com/u/tankygranny05)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tankygranny05/claude-extension-logging

---


# Claude Extension Logging
*[Created by Codex: 019bdeae-0f44-7413-a3f8-47b58a9b4e30 2026-01-21]*

## Overview

Outline how to instrument the Claude extension and shim so the four canonical streams (`claude_extension_to_webview`, `webview_to_claude_extension`, `claude_extension_to_cli`, and `cli_to_claude_extension` for the extension, plus the shim variants prefixed with `claude_shim_`) are always emitted. These logs are the observable record that the shim needs before we compare behavior with Codex.

## When to use this skill

Use this skill whenever you work on observability, debugging, or logging improvements in the Claude ecosystem so that each message path is captured consistently and the new filenames avoid confusion between shim vs. extension traffic.

## Claude extension instrumentation

1. **Ensure log directories exist.** Create `~/centralized-logs/claude-extension/` for the extension and `~/centralized-logs/claude-vscode-shim/` for the shim (or whichever directory the environment requires), and grant write permissions.
2. **Hook the router.** Identify each place in `extension.js` where the extension sends data to the webview or CLI. Before dispatching, append a JSON line to the appropriate file (`claude_extension_to_webview.jsonl` when talking to the UI, `claude_extension_to_cli.jsonl` when talking to the CLI, and the reverse for the other two files).
3. **Share a logger helper.** The helper can look like:

```javascript
const logMessage = (file, payload) => {
  const line = JSON.stringify({
    ts: Date.now(),
    channelId: payload.channelId ?? payload.message?.channelId,
    message: payload
  });
  fs.appendFileSync(path.join(logDir, `${file}.jsonl`), line + "\n");
};
```

Call this helper for every message to ensure the same schema is appended regardless of direction.
4. **Rotate files gracefully.** Trim or archive logs once they hit a few megabytes to keep the observer terminals responsive.

## Claude shim instrumentation

1. **Adopt the `claude_shim_` naming.** Log to `claude_shim_to_webview`, `web_view_to_claude_shim`, `claude_shim_to_cli`, and `cli_to_claude_shim` so the shim’s traffic is instantly distinguishable.
2. **Wrap CLI responses.** Mirror the extension envelope `{"type":"from-extension","message":...}` for every CLI response before logging to `claude_shim_to_webview.jsonl`.
3. **Log inbound UI events.** As soon as messages arrive from the UI, record them to `web_view_to_claude_shim.jsonl` before sending them to the CLI and logging to `claude_shim_to_cli.jsonl`.

## Verification checklist

- Confirm that the eight Claude files exist and append lines when interacting with the UI.
- Use `tail -f ... | jq` to ensure new requests and streaming events appear as expected.
- Run `rg -c '"type":"control_request"'` on the extension and shim logs to verify nothing is missing.
- Rotate logs or truncate them if they grow too large so the observers stay responsive.

## Porting guidance for Codex

When porting this skill to Codex, swap each `claude_` prefix for `codex_` (the files become `codex_extension_to_webview`, `webview_to_codex_extension`, etc.). The same helper, directories, and verification steps apply so the observability story remains mirrored across both ecosystems.