FOLLOW-UP · PRACTICAL RUNBOOK

Continue Claude Code Sessions with GPT-6 Astra: Windows Operations Playbook

Once the bridge is installed, the real goal is repeatability: launch → verify → preserve session continuity → take the smallest corrective action when something fails.

Topic · AI developer tooling / operationsEnvironment · Windows · PowerShellFormat · follow-along runbook

This follow-up to the setup guide explains how to repeat and audit the existing Claude Code ↔ Codex workflow.

Scope firstThe codex-for-claude-code package is a third-party open-source bridge, not an official OpenAI or Anthropic integration. If you only need to delegate reviews or tasks to Codex from inside Claude Code, OpenAI’s official codex-plugin-cc is a more direct option. This playbook documents the narrower case where you intentionally use Claude Code’s TUI while routing Codex model IDs through a local bridge.

Some behavior also changed after the original Windows test. This post therefore separates the behavior that was directly observed in the older bridge build from the current upstream documentation.

Astra model	The official model ID is `gpt-6-astra`, with a 1,050,000-token context window published in the API model specification. This does not establish the effective limit of a particular bridge, account and CLI combination.
Codex CLI	Check the installed Codex CLI release notes for Astra support and known issues. An older version number alone does not establish current bridge compatibility or account availability.
Bridge	Current upstream requires Node.js 20+, a logged-in Codex CLI, and uses a local proxy on 127.0.0.1:3099.
Sessions	An older 0.2.6 test required manual JSONL copying; current upstream documents session/history interoperability, so copying is now a fallback.

Primary sources: GPT-6 Astra model docs · Codex releases · codex-for-claude-code README

System architecture showing Claude Code connected through the local codex-for-claude-code bridge to Codex CLI running GPT-6 Astra — Keep the existing Claude Code session and workflow while requests pass through the local proxy to GPT-6 Astra.

Daily use: the 30-second rerun

After one successful setup, use the public script included in the download package nv-codex.ps1 from the project directory.

.\nv-codex.ps1

Or point it at a project explicitly:

.\nv-codex.ps1 -ProjectPath "C:\path\to\your-project"

If you already know the session UUID:

.\nv-codex.ps1 -ProjectPath "C:\path\to\your-project" -Resume "<SESSION_UUID>"

Success criterionOpening the session is not enough. Run /status and inspect the base URL, model label and prior conversation as initial clues. Verify actual response success, response model and session continuity separately before starting work.

First machine setup: four steps

B1. Preflight

.\nv-codex.ps1 -Check

node --version
claude --version
codex --version
claude-codex --version

Current bridge upstream requires Node.js 20+. Compare the installed Codex and bridge versions with their release notes, then verify support for the intended model and account before proceeding. An update alone does not establish bridge compatibility.

npm install -g @openai/codex@latest

B2. Sign in to Codex

codex login

Use the ChatGPT sign-in route when the purpose is to use the Codex allowance attached to your ChatGPT account. Mixing unrelated router services or custom base URLs breaks the verification assumptions used in this runbook.

B3. Install the bridge

npm install -g codex-for-claude-code@latest

Check claude-codex --help and confirm that --model and --resume are still supported by the installed version.

B4. Launch

claude-codex --model gpt-6-astra

The public script intentionally defaults to the official model ID gpt-6-astra. Non-standard suffixes such as [1m] must not be assumed to work in this bridge. Omit them without evidence of support in the installed version; a suffix or context setting does not increase the actual server limit.

Five-step GPT-6 Astra operations workflow covering restart, initial setup, verification, troubleshooting, and returning to Claude — Restart with one command, perform setup once, verify in 30 seconds, troubleshoot by symptom, and return to Claude safely when needed.

Verification takes 30 seconds; skipping it can waste hours

The most dangerous failure mode is a session that looks healthy while the request path or model is wrong.

Check	Display to check	If wrong
`Anthropic base URL`	`http://127.0.0.1:3099`	`api.anthropic.com`: if this appears after requesting Astra, check model selection and proxy configuration. The displayed address alone does not establish the actual request route.
`Model`	`gpt-6-astra` family	If the displayed model differs from the request, check the selection. A matching label alone does not establish the actual response model.
Session	previous conversation is actually visible	empty history means resume/session visibility is not solved

The bridge README also documents the local 127.0.0.1:3099 proxy and recommends launching codex once to refresh OAuth when a 401 appears.

codex
claude-codex --model gpt-6-astra

Picker behavior is version-sensitivePicker visibility alone does not establish success or failure. Check model support and known issues for the installed version, and compare actual request results with /status together.

Try direct resume first; copy JSONL only as a fallback

The original Windows test with bridge 0.2.6 required copying one session JSONL from ~/.claude to ~/.claude-codex because direct resume could not see the session.

Current upstream documentation now states that current builds preserve session/history interoperability and recommends restarting both TUIs if plain Claude sessions do not appear. That changes the public procedure.

Order	Action
1	Try `claude-codex --model gpt-6-astra --resume <UUID>` directly
2	If history is missing, close both TUIs and relaunch them
3	If resume still fails, verify bridge version and config directories
4	Only then use the script’s `-Import` fallback to copy one JSONL safely

.\nv-codex.ps1 `
  -ProjectPath "C:\path\to\project" `
  -Import "<SESSION_UUID>"

Do not re-import casuallyIf the bridge-side copy already contains newer work, overwriting it can erase that work. The bundled script stops when a target copy already exists; -Force creates a timestamped backup before overwrite.

Safe session management diagram showing selective JSONL migration from regular Claude Code to the bridge environment with backup before overwrite — Session history is a snapshot, not real-time synchronization. Use one side at a time and migrate only the session you need.

If multibyte text is garbled on Windows, check encoding before blaming the model

For projects where CLAUDE.md is a governing document, mojibake is not cosmetic. PowerShell 5.1 can interpret BOM-less UTF-8 through the legacy system code page.

powershell.exe -Command "Get-Content -LiteralPath CLAUDE.md -TotalCount 3"
powershell.exe -Command "Get-Content -LiteralPath CLAUDE.md -TotalCount 3 -Encoding UTF8"

If only the second command renders multi-byte characters correctly, the encoding path is the likely cause.

Choose the least disruptive fixAdding a UTF-8 BOM changes file bytes, which can matter in repositories with sealed hashes or generated-file checks. Consider PowerShell 7 (pwsh) or explicit -Encoding UTF8 rules first when appropriate.

Troubleshoot by symptom, not by rereading the entire guide

Symptom	Smallest next action
401 Unauthorized	Run `codex` once to refresh OAuth, then retry
Could not find Claude Code binary	Set `CLAUDE_CODEX_CLAUDE_BIN` to the real Windows executable path
Git Bash path failure	Convert child-process paths with `cygpath -w`
Astra itself fails	Run a direct `codex exec --model gpt-6-astra ...` test to separate Codex from the bridge
Astra missing from picker	Check installed Codex/bridge versions and the relevant release notes for picker support and known issues
Resume cannot see session	Try current interoperability/restart path first; use Import only as fallback
Port 3099 collision	Check bridge process/health or use an upstream-supported alternate port
Multi-byte text mojibake	Compare Windows PowerShell 5.1 default reading with explicit UTF-8 reading. BOM presence alone does not establish file encoding

Separate Codex from the bridge

codex exec --model gpt-6-astra "Read README.md and summarize it. Do not change files."

If direct Codex works with Astra but claude-codex does not, the bridge layer is now the primary suspect. If direct Codex also fails, start with CLI version, authentication, and account availability.

Returning to Claude: use one side at a time

A copied or independently written session file is not a replicated database. After the switch point, using both configurations can create two different histories.

Do not continue the same session in plain Claude and the bridge at the same time.
Record important bridge-side decisions in a small HANDOFF.md so the reasoning survives even if you discard one history.
Before copying a bridge history back into ~/.claude, back up the original with a timestamp.
If copy-back has not been validated in your environment, handing off decisions into a new Claude session is more conservative than overwriting the original history.

Launching plain Claude is easy; merging histories is notTreat the question “how do I return to Claude?” separately from “how do I merge what happened on the bridge back into the original session?” Automatic merge is not assumed.

What the bundled public PowerShell script does

The downloadable nv-codex.ps1 removes the original machine-specific path. It uses the current directory by default or accepts -ProjectPath.

DOWNLOAD · WINDOWS POWERSHELL

nv-codex.ps1 execution package

Download the public PowerShell script used in this guide as a ZIP package. It includes nv-codex.ps1, an English README, and SHA-256 checksums.

Windows PowerShell nv-codex.ps1 7.3 KiB

Download ZIP

File · claude-code-gpt-6-astra-windows-playbook-en.zip
SHA-256 · c00564155f344867cc816f9d13d5ea3d7bc7774110cf234f6bcb38177688a60a

Review README.txt and the script before running it. Start with .\nv-codex.ps1 -Check to verify your environment.

Option	Purpose
`-Check`	Preflight tools, versions, project path, Claude binary, and CLAUDE.md BOM
`-Resume <UUID>`	Resume one known session directly
`-Import <UUID>`	Fallback: safely copy one JSONL only when direct resume failed
`-Force`	Allow overwrite only after making a timestamped backup
`-Model`	Defaults to official `gpt-6-astra`

.\nv-codex.ps1 -Check
.\nv-codex.ps1
.\nv-codex.ps1 -Resume "<SESSION_UUID>"
.\nv-codex.ps1 -Import "<SESSION_UUID>"

When not to use this bridge

For a new project with no session-continuity requirement, use Codex CLI directly.
If you only want Codex reviews/delegation inside Claude Code, check OpenAI’s official codex-plugin-cc first.
Do not deploy an unofficial local proxy into a company or customer environment where third-party bridges are not approved.
Do not use it where policy forbids local third-party code from reading subscription OAuth material.

This workflow is most appropriate for a personal development environment where preserving Claude Code’s TUI and long-running session context is the explicit goal.

Final operating checklist

	Keep this true
□	Installed Codex and bridge support, release notes and known issues have been checked
□	The requested model is explicitly `gpt-6-astra`
□	`/status` shows the address, model label and prior conversation to check. Actual response success and model verification are separate checks
□	Missing history did not trigger an immediate destructive JSONL overwrite
□	Manual import was preceded by target-copy and backup checks
□	Korean project documents render correctly
□	Plain Claude and bridge histories are not advanced in parallel

One-line summaryDaily operation can be one command, but the /status display is an initial diagnostic hint. Verify actual response success, model and session continuity separately. Keep JSONL copying as a fallback after direct resume and restart paths fail.

Sources: OpenAI GPT-6 Astra · GPT-6 Astra API model · OpenAI Codex releases · codex-for-claude-code · OpenAI codex-plugin-cc