| name | patch-codex-app-server-observability |
| description | This skill should be used when ensuring Codex emits centralized observability logs (sse_lines.jsonl) while running in app-server mode, especially when used by the VS Code extension. |
Patch Codex App Server Observability
[Created by Codex: 019be564-39d9-7b12-a4cf-fb7a7f1af223 2026-01-22]
Purpose
Enable or restore centralized observability (writes sse_lines.jsonl) for the long-lived codex app-server process used by VS Code.
When to Use
- VS Code Codex “New Thread” works but subsequent turns stop producing events in
~/centralized-logs/codex/sse_lines.jsonl.
codex app-server runs fine but the process never opens sse_lines.jsonl.
- A regression between Codex versions removed app-server logging.
- The user sets
"chatgpt.cliExecutable" to a custom codex binary and expects the same observability behavior as terminal runs.
Workflow
- Confirm which
codex binary VS Code is running:
- Check settings for
"chatgpt.cliExecutable" in:
~/Library/Application Support/Code/User/settings.json
<repo>/.vscode/settings.json
- Record the resolved path and
codex --version.
- If the path points to a local repo build, ask the user to confirm the intended repo/branch/commit.
- Confirm the running app-server process and whether it is logging:
- Find the VS Code-started PID (search for
codex app-server).
- Check whether the process has the log file open:
lsof -p <pid> | rg 'sse_lines\\.jsonl|centralized-logs/codex'
- Choose the patch location (prefer least invasive):
- Preferred (matches
codex-cli 0.77.0 behavior): initialize observability in the root CLI when launching codex app-server (no sub-subcommand).
- Alternative: initialize observability inside the
codex-app-server crate (requires a decision on how to choose/configure log dir).
- Implement the root CLI patch:
- In
codex-rs/cli/src/main.rs, before launching the server:
- resolve the effective log dir (root
--log-dir if set, otherwise default via observability::resolve_log_dir)
- call
observability::init(log_dir)
- Keep failure non-fatal (print a warning and continue).
- Keep SIGTERM handler behavior consistent.
- Build and validate:
cargo build -p codex-cli --release
- Ensure VS Code points at the rebuilt binary if
"chatgpt.cliExecutable" is set.
- Restart VS Code to pick up the new binary:
- VS Code keeps
codex app-server alive; reload the window (or kill the app-server PID and let the extension respawn it).
- Re-test:
- Confirm
lsof shows sse_lines.jsonl opened by the app-server process.
- Run multiple turns in one thread; confirm the JSONL file continues to append across turns.
Evidence to Include in RCA
- The exact
codex path VS Code ran (bundled binary vs "chatgpt.cliExecutable" override).
- The
codex app-server command line and PID.
- Whether
lsof shows sse_lines.jsonl open.
- Any stderr warnings emitted when observability initialization fails.