How to Record a Claude Code Session, and Every Other Agent That Will Not Cooperate: A Practical Field Guide

Yes: you can record a Claude Code session today, and what you get is the whole thing (every model turn, every tool call, every file the agent touched) in a form you can replay. That is the short version, and it is true today. The longer version is that recordability is decided per harness, by two questions: can the harness be pointed at a proxy, and is its wire format understood once traffic arrives. Claude Code passes both, and so does a Codex CLI signed in with an API key. An agent with the provider URL hardcoded in its source, an agent running in a container or on a VPS, and a harness signed in with a subscription each take a different path, and one of them, today, does not arrive.

What changed is that these agents stopped being demos. They sit in your repository with shell access, they edit files, they run the test suite, they open pull requests. When one of them does something you did not expect, whether that is deleting the wrong file, looping on the same failing test, or burning an afternoon of compute, the terminal scrollback is not evidence. It is a rendering, and an incomplete one.

What you need is the wire: what was actually sent to the model, what actually came back, and what the agent did between turns. That record is also the beginning of an eval suite, because a captured session is a regression test you can replay against the next model or the next prompt. The catch is that every harness assumes it is talking directly to its provider, and almost none of them make that easy to change.

What decides whether a harness can be recorded?

Every can-you-record-it question collapses into the same two questions.

The first: can the harness be pointed at a proxy? Four routes cover it, in descending order of convenience.

• The base-URL variable. The route built for this: the harness reads a base-URL environment variable, and you set it.

• Spawning the harness yourself. A child process inherits its parent environment, so a gateway that spawns a coding agent is captured too, without the agent's cooperation.

• TLS interception. For the harnesses that read no configuration at all, the recorder launches the agent and you opt into interception.

• Attach. When the agent runs somewhere the recorder cannot launch it, what is left is attach.

If none of those apply, the traffic never reaches the recorder and there is nothing to discuss.

The second: once traffic arrives, is its wire format understood? Capturing bytes is not the product. The recorder has to recognize the conversation it is standing in for, including the tool-call shapes, the streaming frames, and the retries, or the recording is a pcap, not a replay. A format the recorder understands produces a session you can replay; a private dialect produces capture you can only stare at.

The answer differs per harness, and it differs in details that are easy to get wrong: it is the same lesson that fell out of comparing how the DeepSeek harness differs from Claude Code. The rest of this article is what the two questions look like when you actually run the harnesses.

Claude Code, the Codex CLI, and the Agents SDK

Claude Code is the case everything else gets measured against, because it reads ANTHROPIC_BASE_URL. Set that variable to the recorder, start the agent, and the session arrives turn by turn: the prompts, the tool calls, the file edits, the model's replies between them. We validated it end to end against a real bug fix (a real repository, a real defect, a session that runs from the first prompt to the working fix), and that first real agent broke four things that no fixture had produced. All four are since fixed, which is the honest way of saying that synthetic traffic does not prepare you for what a real agent does when it is left alone with a codebase.

The Codex CLI, signed in with an API key, is the same story through OPENAI_BASE_URL. Point it at the recorder and you get the session; nothing else about how you use the harness changes.

Programmatic agents inherit the easiest route of all. A child process inherits its parent environment, so a gateway that spawns a coding agent is captured too, without the agent's cooperation. Set the base-URL variable once in the process that does the spawning, and every agent it launches arrives at the recorder on its own. If you run agents from CI, from an orchestrator, or through the Agents SDK, this is the path you are already on.

The recorder in all of these cases is OrcaReplay. It installs with npm i -g orcareplay, needs Node 20 or newer, and has no native dependencies: nothing to compile, nothing to build. It captures the same agent traffic that OrcaRouter routes across OrcaRouter's model catalog.

An agent that reads no base-URL variable

Some harnesses hardcode the provider URL in their source. No environment variable, no config file, no flag. Setting ANTHROPIC_BASE_URL does nothing, because nothing reads it. If the recorder can launch the agent, there is still a route, and it is the one people worry about most: TLS interception.

Opting in is exactly that, an opt-in; it is off by default. When you enable it for a run, the recorder mints a certificate authority unique to that run, and that authority is trusted only by the agent the recorder launches: it is handed to that one process, not installed in your system keychain, not left behind for the next run. When the run ends, the authority is deleted. The agent connects to its hardcoded host exactly as it always did; the recorder answers, and the session arrives as if the URL had been configurable all along.

What the route deliberately refuses matters as much as what it does. It reads the hosts on its allowlist and nothing else. Hosts outside the allowlist are tunnelled unread and recorded as an address and a byte count: proof that the agent contacted something, and not one byte of what was said. That boundary is a design decision, not a limitation we have not gotten to yet; the same discipline runs through OrcaRouter's agent firewall, where the allowlist is the product rather than a side effect of recording.

The catch is the one from the first question: interception works when the recorder launches the agent. An agent already running inside a container never received that run's certificate authority, and it will not trust the recorder's answer.

An agent that is not on this machine

A container has its own environment. The base-URL variable you set in your shell does not reach inside it, and a recorder on the host cannot launch a process that already exists somewhere else: on a VPS, in CI, in a sandbox the harness built without asking you. Launch-based capture fails here not because the agent is difficult but because the recorder never gets to touch it.

For exactly this case there is orca attach: it records an agent the recorder cannot launch, such as one in a container or on a VPS. The direction flips: instead of the recorder starting the agent and handing it an environment, it attaches to an agent that is already running and records it.

What attach does not do is answer the second question for you. It solves getting the traffic to the recorder; whether that traffic becomes a session you can replay still depends on the wire format being understood. Attach an agent that speaks a format the recorder knows and you get a replayable session. Attach one that does not, and you have found the wall, which is cheaper to find on purpose than mid-incident.

What does a subscription login change?

The same binary can be recordable or not depending on how it signed in. A Codex CLI signed in with an API key is captured through OPENAI_BASE_URL: point it at the recorder and you are done. Sign the same CLI in with a ChatGPT subscription and it stops talking to that endpoint entirely; it talks to its own backend, authenticated as you, and there is no origin to rewrite. The base-URL variable still exists, but nothing you point it at becomes the service the harness is actually using.

This is the second question failing, not the first. The bytes can be made to move; the recorder can even see them. But the conversation is addressed to a backend the recorder cannot stand in for, in a flow that is not the API the recorder speaks. There is no replay to produce because there is no origin the recorder can become.

The honest answer for a subscription-signed harness, today, is that it is not recordable, and the useful lesson is that the sign-in method is part of the recordability decision. If you need recordings for evals or for an audit trail, run the recorded sessions on an API key and keep the subscription for interactive work — how to turn a recorded session into a regression eval covers that loop end to end. And before you standardize on any harness, put the two questions to it first; we keep doing exactly that per harness, most recently with the Prime Agent harness.

The takeaway

You can record a Claude Code session today with one command and one environment variable:

• npm i -g orcareplay

• Point ANTHROPIC_BASE_URL at the recorder

• Run the agent

A Codex CLI on an API key is the same distance away. A hardcoded URL costs you an opt-in to TLS interception that reads only its allowlist (the same discipline OrcaRouter's agent firewall enforces) and forgets its own certificates when the run ends. A container or a VPS costs you orca attach. A subscription login costs you the recording itself: that harness will not be recorded, and no configuration changes that today.

The whole decision at a glance:

• Claude Code — Sign-in API key vs Route to the recorder ANTHROPIC_BASE_URL vs Recordable today Yes

• Codex CLI — Sign-in API key vs Route to the recorder OPENAI_BASE_URL vs Recordable today Yes

• Harness with the provider URL hardcoded — Sign-in Any vs Route to the recorder Opt-in TLS interception, launched by the recorder vs Recordable today Yes

• Agent in a container or on a VPS — Sign-in Any vs Route to the recorder orca attach vs Recordable today Yes, if the wire format is known

• Codex CLI — Sign-in ChatGPT subscription vs Route to the recorder None vs Recordable today No

The last row is the only combination with no route to the recorder at all.

Ask the two questions before you adopt a harness, not after your first incident; the answers are cheap to get, and they decide whether the session you will one day desperately need exists at all.

Sourcing note: every behavior and figure in this article (the `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` capture paths, the four post-fixture breakages and their fixes, the TLS certificate lifecycle, the allowlist-and-tunnel behavior, `orca attach`, and the install requirements) comes from our own validation runs against the harnesses named, most recently on 2026-09-04. We cite no third-party benchmarks because we ran none.