claude-extension-logging

name	claude-extension-logging
description	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.

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:

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.