Codex Extension Logging

[Created by Codex: 019bdeae-0f44-7413-a3f8-47b58a9b4e30 2026-01-21]

Overview

Document how to capture the four directional Codex traffic streams so they match the renamed JSONL files (codex_extension_to_webview, webview_to_codex_extension, codex_extension_to_cli, and cli_to_codex_extension for the extension, plus the shim variants prefixed with codex_shim_). These logs feed the observer workflows and keep the shim aligned with Claude behavior.

When to use this skill

Trigger this skill when adding or updating Codex-side observability, whenever a question arises about missing messages, or before you build new observer tooling that needs predictable filenames. The instructions ensure the extension and shim continue to emit the canonical streams so diffing against Claude is straightforward.

Codex extension instrumentation

1. •Prepare log directories. Create ~/centralized-logs/codex-extension/ (extension logs) and ~/centralized-logs/codex-vscode-shim/ (shim logs, if shared) and ensure the file owner can write there.
2. •Instrument the message router. Wrap the code paths in extension.js that pass messages between the webview and CLI. Before webview.postMessage or CLI writes, append JSON.stringify({ts: Date.now(), channelId, message: payload}) to the right file: codex_extension_to_webview.jsonl when sending to the webview, codex_extension_to_cli.jsonl when touching the CLI, and the reverse for webview_to_codex_extension.jsonl and cli_to_codex_extension.jsonl.
3. •Use a shared logger helper. Keep a helper such as:

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");
};

Apply it wherever traffic is forwarded so every logical hop writes the same structured line. 4. Rotate sensibly. Truncate or rotate the files when they exceed a few megabytes to keep the observer panes responsive.

Codex shim instrumentation

1. •Mirror the naming. Use codex_shim_to_webview, web_view_to_codex_shim, codex_shim_to_cli, and cli_to_codex_shim as file basenames in the shim’s log directory.
2. •Wrap CLI responses. Before forwarding CLI output to the webview, wrap it in {"type":"from-extension","message":…} (just like the real extension) and append to codex_shim_to_webview.jsonl so the logged stream reflects exactly what the UI receives.
3. •Log inbound UI events. Capture each message arriving from the webview before the shim transforms or filters it, writing to web_view_to_codex_shim.jsonl, then forward it to the CLI latch that logs to codex_shim_to_cli.jsonl.

Verification checklist

• •Confirm all eight Codex files exist under the log directories and are being appended to during interactive sessions.
• •Tail each (tail -f … | jq) to check every new request or stream event shows up.
• •Run rg -c '"type":"control_request"' across the extension/cli logs to compare counts against Claude’s logs.
• •Mirror the same checks on the shim logs to ensure symmetry.

Porting guidance for Claude

Copy these instructions to the Claude skill, replacing each codex_ prefix with claude_ (e.g., claude_extension_to_cli, cli_to_claude_extension). The helper logic, directory layout, and verification checks stay the same so the two sets of observability tooling remain aligned.