# Codex Extension Logging

> Document how to add directional logging to the Codex extension and shim so the four canonical JSONL streams (extension↔webview and extension↔CLI) are captured consistently and can be compared against Claude logs.

- Skill: `tankygranny05/codex-extension-logging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/codex-extension-logging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/codex-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/codex-extension-logging

---


# 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:

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

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.