Claude Code vs Codex: Seven Protocol Differences We Encountered After Connecting Two Engines to the Same Remote System

Disclosure of Interest: We develop PandaNpc — a system that allows coding agents such as Claude Code and Codex to be accessed remotely and shared by multiple users. Because we needed to support all these engines simultaneously within the same page and the same message pipeline, we had to align their protocol behaviors one by one. This article documents the differences we actually encountered in that process — it is not a benchmark comparison — we have not conducted any controlled benchmark tests, so no test numbers such as speed or success rates will appear here. Future plans are described at the end.

Note: In this article, Codex refers to the OpenAI Codex command-line tool, not other products with the same name.

One-sentence conclusion: For standalone use on a local machine in the terminal, the experience difference between the two is far smaller than you might expect; once you need to integrate them into your own system (remote control, multi-device sync, session recovery, tool approval), the differences are almost entirely concentrated in the protocol layer — and these are differences we could not have learned about in advance from the documentation; we only discovered them by running into them.

If you are searching for Codex vs Claude Code because you want to know "which one should I choose," this article may not be the kind of head-to-head comparison you are looking for — it does not compare which one writes code better. Instead, it answers a more specific question: what will you encounter when you need to treat them as a programmable backend to integrate with?

Who Should Read This

• Developers who want to support both engines at once, or migrate from one to the other
• People who want to build peripheral tooling such as remote control / multi-device sync / session sharing
• People who want to know "what exactly is different about the session models of these two CLIs"

If you just want to write code on your own computer and have no plans to do integration, this article is of limited value — reading the two official documentation sites directly will be faster.

First, the Common Ground: Why They "Look the Same"

Before discussing the differences, it is worth making clear: the mental models of these two tools are highly similar — both run in the terminal, both are organized around sessions, both can call tools to modify files and run commands, both require user confirmation for dangerous operations, and both can handle multiple rounds of tasks continuously within a single session. This is precisely why, when doing integration, it is easy to form the judgment that "one adapter layer is enough for both" — and that is exactly how we started.

The differences are not at the capability layer; they are at the protocol layer. In other words, the behavior you see in the terminal can be nearly identical, but the frames they emit, the order of those frames, and how the fields are organized are all different. This is why such differences are hard to discover in advance: when you use them on your own computer, you will never run into them.

Quick Reference Table of Seven Differences

#	Dimension	Claude Code's Behavior	Codex's Behavior	Who Gets Bitten If Not Handled
1	Assistant message identifier	Has stable id	May not have one	People doing message persistence / multi-device sync
2	Session liveness check	Batch form, one group at a time	Expects a single session id	People doing online status display
3	History replay ordering	Consistent with real chronological order	Sub-thread activity frames appear in one batch at the end	People doing sub-agent / multi-thread views
4	Tool call command structure	Complete	May be fragmented	People building tool approval UIs
5	Channel event subscription	Acts as the executor of session switching	Cannot perform the switch at the same time	People doing multi-path relay
6	Online connection quota	Shares the same counting pool as Codex	Same as left	People doing quota limits
7	Long-history performance	Linear	Can degenerate to non-linear if mishandled	People doing mobile clients

Below, each one is expanded in detail, written in the format of "symptom → how to locate → how to fix."

1. Whether Assistant Messages Have a Stable id — This Determines Your Deduplication Strategy

Symptom: Open a Codex session, and everything is normal right after chatting; exit and click back in, and the same assistant reply has become 2 copies, then 3 copies — more copies every time you re-enter. Messages sent by the user are unaffected; only assistant replies multiply. Claude Code sessions do not exhibit this.

How to locate: This symptom is extremely easy to misdiagnose as a client-side rendering issue or duplicate history loading, after which you dive headfirst into frontend debugging. The correct first step is to directly check how many records are actually stored in the server-side cache — if the cache really contains N records, then the problem is in the data layer, unrelated to rendering. This step is precisely what pulled us back from the client side back then.

Root cause: Claude Code assistant messages carry a stable identifier, so they can be deduplicated directly by id when replay and real-time push arrive. Codex-side assistant messages are not guaranteed to carry such an identifier, so when the same "deduplicate by id" logic is reused, the same reply gets written in as two different messages.

How to fix: For messages without a stable id, switch to "round anchor + content" folding — the anchor is the hash of the most recent user message preceding this reply.

⚠️ There is a pitfall here worth calling out separately: our first version folded by plain text. After going live, when we scanned historical data, we found that it had wrongly deleted 691 identical replies across rounds. The reason is that Codex's short replies have an extremely high repetition rate ("OK." "Done." and the like), and the deduplication set was session-scoped — once the hash of a phrase was recorded, the same phrase in any later round within that session would be swallowed. That was content loss, which is more serious than duplication. The anchor layer cannot be omitted.

2. Liveness Check: One Wants a Single Item, the Other Is Batch

Symptom: The session is clearly still running, but the interface shows it as offline.

How to locate: This difference looks very much like it can be generalized — the field names on both sides are similar, so when writing the code it is easy to assume one set of code can handle both. The judgment method is simple: send the batch structure over and see whether the response has the shape you expect.

Root cause: For determining "is this session still alive," the two sides have different interface shapes. On the Claude Code side, we use a batch form that carries a group of session ids at once; the Codex side expects a single session id.

How to fix: Use two separate call paths; do not try to share one. This difference is not difficult to handle by itself — the trouble is that it does not report errors: sending the wrong structure will not throw an exception, it will only return an answer that is semantically wrong.

3. History Replay Frames Are Ordered Differently — Sub-Agent State Gets Stuck

This is the most circuitous one to debug.

Symptom: The sub-agent status dot in the sidebar is still orange, "running," still breathing, when in reality it finished or was interrupted long ago. Refreshing the page does not fix it either — every refresh replays the error once more. This only appears in Codex sessions.

How to locate: "Refreshing does not fix it" is the key criterion. It tells you the problem is not in real-time push but in the history replay itself — every replay rewrites the state incorrectly again.

Root cause: During replay, all entries of the parent thread are laid out first (including the notification frames that say "sub-agent has ended"), then the activity frames of each sub-thread are appended in one batch at the end. So the order the client receives is: first the "interrupted" notification, then activity frames that are chronologically earlier. And the logic that writes state does not compare timestamps — that final batch of earlier frames unconditionally overwrites the terminal state back to "running."

How to fix: Add a terminal-state guard to the branch that writes state — once a state is already terminal (completed/failed/stopped), only a later frame may override it. Note that the criterion should share the same state mapping used elsewhere; do not write a second mapping, or the two places will drift on what counts as "terminal."

The common characteristic of this class of problem is: any single frame considered in isolation looks valid — what is wrong is their relative order. So staring at logs of individual frames will never reveal the problem.

4. Tool Call Command Structure: It Can Be Fragmented

Symptom: In Codex sessions, tool cards display commands as fragments like 1,220p or /pid=…/ {print}; sometimes an entire script is split apart, and sometimes after the answer finishes, a batch of unfinished tool cards is still hanging around.

How to locate: Look at the actual structure of the command field in the raw frames, not at the rendered result. If you follow Claude Code's field path to fetch "what command the user executed," what you get is the chopped-up fragments.

How to fix: Write a separate command reassembly layer for Codex, stitching the fragments back into a complete command before handing it to the UI.

This difference is especially fatal for people doing tool approval: the user has to tap "allow / deny" on their phone, but the command displayed on the card is fragmented — that is equivalent to asking someone to sign blind. A security feature losing its meaning is far more serious than a display looking ugly.

5. The Subscription Surface of Channel Events Differs

Symptom: Two users kick each other offline.

Root cause: If both relay paths subscribe to and execute "session switch"-type events, each side kicks out one victim, resulting in a double eviction. The switching action must have a single executor.

How to fix: Our approach is to have the Codex path subscribe only to kick and cache-invalidation events, never to switch events, pinning the execution authority of switching to the other path.

Decisions of this kind — "deliberately not doing something" — usually leave only a single line of comment in the code, but they were added only after being bitten once. And once a later person "helpfully completes" such a constraint, the incident recurs. So the comment should explain why it is not done, not merely state that it is not done.

6. Quota and Connection Counts Are Combined

Symptom: The user thinks there is still quota left, but in reality they have already exceeded it.

Root cause: If you impose a limit on online connection counts, as we do, you should note that connections from both engines fall into the same counting pool. When a user has Claude Code and Codex sessions open at the same time, they consume the same quota.

This is not a defect; it is a design choice — from the user's perspective, "how many sessions can I have open at once in total" is easier to understand than "how many of each engine can I open." But if your implementation counts per engine separately, the remaining quota shown in the frontend will not match the actual deductions in the backend.

How to fix: First decide clearly which accounting basis you want, then make sure the frontend and backend use the same one. Mixing the two accounting bases is worse than choosing the wrong one.

7. Performance Characteristics Differ as History Grows

Symptom: Opening a long-history session on mobile causes a freeze.

Root cause: We hit an obvious freeze once on iOS. The root cause was an operation in history processing that grows quadratically with the number of messages. It should be noted that this is not a problem with the engine itself — it is caused by the mismatch between its history structure and our original processing approach — the same processing approach never surfaced this issue on the other engine.

How to fix: Replace repeated scans that grow with message count with a one-time index. More importantly, design in advance: long history must be taken into account from the very beginning; you cannot wait until users have accumulated thousands of messages to discover the problem.

So Which One Should You Choose

A note first: the following is advice from the integration perspective, not an evaluation of coding capability. We have not conducted controlled benchmark tests, and any claim like "X is faster by some amount" will not come from this article.

Cases Where Codex Is a Better Fit

1. Your team is already in the OpenAI ecosystem — accounts, quotas, and billing are all in one place, one less set of accounting and credential management. This convenience should not be underestimated.
2. Your workflow is already built around its session and task model — refactoring peripheral tooling for the sake of migration is usually not worth it. The seven differences above, reversed, are exactly the migration cost.

Cases Where Claude Code Is a Better Fit

1. You want to build peripheral tooling yourself — from our integration experience, messages carrying a stable identifier make persistence and multi-device sync much easier. Differences 1, 3, and 4 are all easier to handle on this side.
2. You want to build interactions such as tool approval — the command structure is complete, so no additional stitching is needed for the approval UI, and there is no "blind signing" risk.

Cases Where You Choose Neither

If your need is merely "run the same interactions with a different model," then switching engines is less effective than switching the model backend. Part of the reason we built PandaCode is precisely this: keep the interaction layer unchanged, and swap out the model.

If You Are Migrating: The Amount of Rework Corresponding to the Seven Differences

Many people search for these two names because they are actually evaluating "if I already use one, how much will it cost to switch to the other?" Below, the seven differences above are converted into migration cost.

A note: this section is the amount of rework derived from the seven differences above, not a record of a complete migration we performed — our path was "integrating both simultaneously," not "switching from one to the other." So treat it as a checklist, not an estimate of working hours.

Migrating from Claude Code to Codex, the rework is concentrated in these areas:

• Deduplication logic must be rewritten (Difference 1) — this is the easiest one to underestimate. Code that deduplicates by id cannot be reused directly, and being wrong does not produce an error; it only silently duplicates messages or silently drops them. If you have message persistence, you must decide what your anchor is before migrating.
• The online status check needs a different call shape (Difference 2) — small effort, but missing it results in "running but shown offline," and no exception is thrown.
• Everything that depends on history chronology must be re-validated (Difference 3) — sub-agent views, progress bars, and any logic that "infers current state from history" all fall into this category.
• The tool approval UI needs a command reassembly layer (Difference 4) — if your product has an approval feature, this one cannot be omitted; otherwise it is equivalent to making users sign blind.

The reverse direction (Codex to Claude Code) is usually less work: deduplication can be simplified back to by-id, and the command structure needs no reassembly layer. But be careful not to simply delete the compatibility layer written for Codex — if you still want to keep the ability to support both, that layer is an asset, not a liability.

Things both directions must re-verify: quota accounting (Difference 6) and long-history performance (Difference 7). These two are less directly tied to the engine, but they are the parts most easily forgotten to re-test after switching engines.

One piece of advice: if your system is already in production and has existing session data, run the new logic against the existing data as a comparison before migrating — do not switch directly. The lesson from our deduplication mistakenly deleting 691 records came from exactly this: the logic itself looked fine; only after scanning historical data did we find that it would swallow content. The new logic being correct ≠ it being safe for existing data.

What We Do: Don't Choose; Integrate Both

Because we needed to support both, our final conclusion was to absorb the differences in the middle layer — expose a unified message and session model upward, and adapt per engine downward. The cost is that every time an engine is added, all seven categories of behavior above must be re-aligned; the benefit is that users can freely switch engines in the same interface, and the experience of sessions, history, and approval remains consistent.

Verification Checklist for Integrating a New Engine

If you are going down this path too, we recommend verifying in this order: the first four items determine whether it works at all; the last three determine whether there will be incidents in production:

1. Message identifier — do assistant messages have a stable id? If not, what is your deduplication anchor?
2. Session liveness — does the liveness check endpoint accept a single item or a batch? If you send the wrong structure, does it error out, or silently give a wrong answer?
3. History replay order — is the replayed frame order consistent with real chronology? Especially when sub-threads are involved.
4. Tool call structure — is the command field retrieved complete? Does it get chopped up?
5. Event subscription surface — which events must have a single executor? What happens if executed twice?
6. Quota accounting — is the count per engine or combined? Are frontend and backend consistent?
7. Long-history performance — when message count increases tenfold, does processing time grow linearly or faster?

For each item, we recommend verifying once with a small amount of data, then once with a large history — items 3 and 7 only surface after the data volume increases.

Reverse Lookup by Symptom: Which One Did You Run Into

If you have already hit a problem, working backward from the symptom is usually faster than reading through the documentation:

Symptom You See	Most Likely Cause	One-Step Diagnosis Method
Assistant replies multiply after exiting and re-entering	Difference 1 (message identifier)	Check directly how many records are stored in the server-side cache — data layer or rendering layer, you will know at a glance
Session is running but shown offline	Difference 2 (liveness check)	Check whether the liveness request sends a single-item or batch structure
Sub-agent state stuck at "running," refreshing does not fix it	Difference 3 (replay order)	"Refreshing does not fix it" is the criterion: the problem is in replay, not real-time push
Commands on tool cards are fragmented / tool cards still hanging after the answer ends	Difference 4 (command structure)	Look at the structure of the command field in raw frames, not the rendered result
Two users kick each other offline	Difference 5 (subscription surface)	Check whether two executors are handling the switch event simultaneously
Frontend shows quota remaining, backend already exceeded	Difference 6 (quota accounting)	Confirm whether frontend and backend count per engine or combined
Opening long sessions on mobile freezes	Difference 7 (long history)	Compare processing time with sessions whose message counts double, and see whether it is non-linear

A general criterion: if the symptom reproduces stably on every refresh, the problem is most likely in history replay or the data layer; only if it occurs sporadically during real-time interaction should you investigate the push pipeline. This criterion has saved us a fair amount of time — differences 1 and 3 were both initially misdiagnosed as client-side problems.

FAQ

Are the Codex CLI and OpenAI Codex the same thing? Codex as discussed in this article refers to OpenAI's command-line coding tool. There are other products on the market also called Codex (including some software in the legal and compliance space), which are easy to confuse when searching. Adding "CLI" or "OpenAI" as a qualifier will be much more accurate.

Do these differences change with versions? Yes. Each item above is a behavior we encountered at a specific point in time, and both are iterating rapidly. So the verification checklist is the more important takeaway — the specific differences will change, but the dimensions that need verification are unlikely to change.

Can I integrate both engines at the same time? Yes, we do exactly that. The key is to absorb the differences in the middle layer rather than letting them leak into the UI layer — otherwise, every time an engine is added, the interface logic forks once more.

Future Plans

We plan to add a set of controlled task tests (the same batch of tasks, fixed versions, public methodology, and raw outputs), and we will update this article with the results when they are ready. Until then, this article contains no performance or success-rate numbers — we will not write that we tested something we have not tested.

---

This article is based on our actual engineering experience integrating Claude Code and OpenAI Codex into the same remote-access system, last updated on 2026-08-26. Both engines are continuously updated; please refer to their respective official documentation for specific behavior.