Fixing the Codex CLI Windows Hang

Ethan Park

Thanks to Jellypod to help make this daily show a reality, today we're talking about a particularly frustrating issue hitting Windows developers using the Codex CLI. It's a silent hang where the CLI just sits there indefinitely showing a "Working" status right after a local PowerShell tool call completes. Maya, you actually ran into this first hand during a launch prep, didn't you?

Maya

Oh, absolutely. [sighs] I was running a simple ripgrep search through PowerShell using `rg` to find some configuration strings. The tool finished instantly, returned the correct results to my terminal, and then... nothing. Codex just sat there, spinning on "Working," consuming zero CPU, but completely unresponsive. I had to manually kill the terminal process.

Ethan Park

And the reason this happens is surprisingly low-level. It's not a network drop or an API rate limit. It comes down to manual string interpolation inside the CLI's transcript serialization. Instead of passing the tool's output to a robust, safe JSON serializer, the engine was manually concatenating strings to write the local session history into a JSONL, or JSON Lines, file.

Maya

Wait, [skeptical] manual string concatenation for JSON? That's Web dev 101 of what not to do. If the tool output contains unescaped double quotes or non-ASCII characters, the entire JSON structure breaks down.

Ethan Park

Exactly. In this case, ripgrep returned code snippets containing double quotes, and PowerShell piped them out using its default non-UTF-8 encoding, creating Mojibake. The serializer wrote raw, unescaped quotes directly into the `function_call_output` field of that JSONL line. That means you end up with a malformed JSON line in your local session transcript.

Maya

Right, so the file on disk is corrupted. But why does a local malformed JSON file cause the active HTTPS connection to hang? You'd think the local CLI would just crash with a JSON parse error.

Ethan Park

You would think so! But here is the sequence of events. When Codex prepares to send the next interaction to the server, it reads the local JSONL file to reconstruct the conversation history. It parses the lines, hits the malformed `function_call_output` block, and fails silently or partially. Then, it initiates a `responses_http` POST request to `chatgpt.com/responses` to send the state payload.

Maya

Ah, [realization] so the payload itself is corrupted or incomplete, and because of how the API client is configured, it sends a bad request body but keeps the connection open, waiting for a response that the server is never going to send.

Ethan Park

Spot on. The connection stays wide open, the socket doesn't time out, and because there's no client-side timeout handling that specific state, the user is left looking at "Working" forever.

Maya

Okay, so if we are stuck in this state right now, how do we actually find where the corruption is? Where is this JSONL file stored, and what are we looking for?

Ethan Park

You need to look in your local Codex state directory. The session transcripts are typically stored as `.jsonl` files named after your active thread ID. Open that file in a proper text editor, and look at the very last line. If you see unescaped quotes inside the `function_call_output` JSON block, or blocky Mojibake characters where UTF-8 characters should be, you've found the culprit.

Maya

So to recover immediately, can we just delete that corrupted line, or do we have to wipe the whole session?

Ethan Park

You have two choices. If you want to save the session, you can open the file, delete the corrupted line entirely, or truncate the file to the last known-good turn, and save it. If you don't care about the history, the easiest path is to just start a clean thread using `codex --new-thread`.

Maya

That's a good quick fix, but we need to stop it from happening again the next time a tool returns a non-ASCII character or a quote. How do we fix the PowerShell encoding side of things?

Ethan Park

This is the crucial step for Windows users. PowerShell's default output encoding is often set to regional ANSI code pages, like Windows-1252. To force UTF-8, you need to configure your PowerShell profile. Run these two commands to force UTF-8 globally for your session: `$OutputEncoding = [System.Text.Encoding]::UTF8` and `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`.

Maya

[thoughtfully] Putting those two lines into your `$PROFILE` script is basically mandatory if you're running local tools with Codex on Windows. It ensures that when tools like `rg` or `dir` write to stdout, PowerShell doesn't transform high-ASCII characters into garbage that breaks the transcript serializer.

Ethan Park

Exactly. And on the build side, there's good news. If you upgrade to the latest `0.142.0-alpha` release, they've started addressing these serialization bottlenecks. They've also updated their environment setup, moving to `uv sync` for managing the Python SDK dependencies, which makes local environment rebuilds much faster and cleaner.

Maya

That `uv sync` addition is huge for keeping the Python environment stable. So, update to `0.142.0-alpha`, force UTF-8 in your PowerShell profile, and if you get a silent hang, check your local `.jsonl` file.

Ethan Park

That's the playbook. Thanks for listening, and we'll catch you on the next one.