FOLLOW-UP · PRACTICAL RUNBOOK

Setup is done. Now switch in one command: a Windows operations playbook for continuing Claude Code sessions with GPT-6 Astra

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 is the operational follow-up to the setup guide. The goal is not to relearn the bridge every time, but to make the same Claude Code ↔ Codex workflow repeatable and auditable.

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 published 1,050,000-token context window.
Codex CLI	Astra API configuration support was added in 0.153.1; 0.153.4 fixed bundled picker visibility and default-model behavior.
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 immediately and verify the base URL, model, and actual historical conversation before doing any 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+. Astra API configuration support is documented in Codex 0.153.1, and 0.153.4 fixes Astra visibility in the bundled picker. For a new setup, update to the current stable CLI instead of targeting the oldest possible version.

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] should be treated as optional client/bridge hints, not as part of the official model ID.

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	Expected	If wrong
`Anthropic base URL`	`http://127.0.0.1:3099`	`api.anthropic.com` means the bridge did not take over
`Model`	`gpt-6-astra` family	A different default model suggests fallback
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-sensitiveCodex 0.153.1 added Astra API configuration while keeping it out of the picker in that release path. Codex 0.153.4 later fixed Astra visibility in the bundled picker. Do not memorize “missing from picker is normal”; check the installed version and /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 Korean text breaks on Windows, inspect 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 Korean 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 Codex version; distinguish 0.153.1 behavior from 0.153.4+ behavior
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
Korean text mojibake	Inspect PowerShell 5.1 encoding behavior

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 4.0 KB

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
□	Codex and the bridge are on a current stable build
□	The requested model is explicitly `gpt-6-astra`
□	`/status` shows localhost:3099, Astra, and real prior history
□	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 verification is the actual gate. 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