[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80417":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":13,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},80417,"claude-codex","fuergaosi233\u002Fclaude-codex","fuergaosi233","Remote-mode adapter that lets the Codex desktop app talk to Claude Code through the native Codex app-server protocol",null,"TypeScript",61,6,1,0,3,4,2.54,"MIT License",false,"main",true,[],"2026-06-12 02:04:02","# Claude Codex Adapter\n\nRemote-mode adapter that lets the Codex desktop app talk to Claude Code through\nthe native Codex `app-server` protocol.\n\nThe intended deployment is a remote SSH host with a `codex` shim earlier in the\nlogin-shell `PATH`. Codex App still performs its normal SSH version probe,\nbootstrap, and `app-server proxy` flow, but `codex app-server` is handled by this\nadapter instead of the real Codex runtime.\n\n## Build\n\n```bash\nnpm install\nnpm run build\n```\n\nThe adapter requires **Node.js 24+** for stable `node:sqlite`. Node 22 ships\n`node:sqlite` behind `--experimental-sqlite`, which the adapter does not pass,\nso it crashes at runtime on 22 even though it imports cleanly on 24. Set\n`CLAUDE_CODEX_NODE` in the shim environment to pin a specific node binary.\n`@anthropic-ai\u002Fclaude-agent-sdk` is the only runtime dependency for Claude\nitself — the prior Python sidecar (`python\u002Fclaude_sidecar.py`) is gone; the\nTS SDK is loaded in-process and ships its own `claude-code` native binary via\nnpm `optionalDependencies` for the host platform.\n\n## Remote shim\n\nInstall `scripts\u002Fcodex-shim` as `~\u002Fbin\u002Fcodex` on the remote host and make it\nexecutable:\n\n```bash\nmkdir -p ~\u002Fbin\ncp scripts\u002Fcodex-shim ~\u002Fbin\u002Fcodex\nchmod +x ~\u002Fbin\u002Fcodex\n```\n\nThen ensure the remote login shell exports:\n\n```bash\nexport PATH=\"$HOME\u002Fbin:$PATH\"\nexport ANTHROPIC_API_KEY=\"...\"                    # or sign in with `claude \u002Flogin`\nexport CLAUDE_CODEX_ADAPTER=\"\u002Fopt\u002Fclaude-codex-adapter\u002Fdist\u002Fsrc\u002Fadapter.mjs\"\nexport CLAUDE_CODEX_NODE=\"\u002Fabsolute\u002Fpath\u002Fto\u002Fnode\" # optional\nexport CODEX_REAL=\"\u002Fusr\u002Flocal\u002Fbin\u002Fcodex.real\"     # optional fallback\n\n# Optional: route Anthropic API traffic through a reverse proxy. Useful when the\n# remote host's egress IP is region-blocked from api.anthropic.com but you still\n# want the same `claude` CLI auth (claude.ai OAuth or ANTHROPIC_API_KEY).\n# export ANTHROPIC_BASE_URL=\"https:\u002F\u002Fyour-anthropic-reverse-proxy.example\"\n```\n\nCodex App Remote should continue to use its native SSH flow. The app probes\n`codex --version`, starts `codex app-server --listen unix:\u002F\u002F`, then connects via\n`codex app-server proxy`. The shim routes only those app-server calls to this\nadapter.\n\n### Bootstrapping a fresh remote host (macOS \u002F Linux)\n\nA clean machine usually only needs four user-space tools. The pattern below\nworks without `sudo` or Homebrew and is what the project's macOS deployments\nuse:\n\n```bash\n# 1. Node 24 (stable node:sqlite). Pick your platform tarball from\n#    https:\u002F\u002Fnodejs.org\u002Fdist\u002Fv24.11.0\u002F and extract under ~\u002F.local.\ncurl -fsSL https:\u002F\u002Fnodejs.org\u002Fdist\u002Fv24.11.0\u002Fnode-v24.11.0-darwin-arm64.tar.xz \\\n  | tar -xJ -C ~\u002F.local\n\n# 2. Claude Code CLI, installed under a user prefix so no sudo is needed.\nmkdir -p ~\u002F.local\u002Fnpm-global\n~\u002F.local\u002Fnode-v24.11.0-darwin-arm64\u002Fbin\u002Fnpm config set prefix ~\u002F.local\u002Fnpm-global\n~\u002F.local\u002Fnpm-global\u002Fbin\u002Fnpm install -g @anthropic-ai\u002Fclaude-code\n~\u002F.local\u002Fnpm-global\u002Fbin\u002Fclaude \u002Flogin   # interactive: claude.ai OAuth\n\n# 3. Adapter checkout + build (also installs @anthropic-ai\u002Fclaude-agent-sdk).\ngit clone \u003Cthis repo> ~\u002Fclaude-codex\ncd ~\u002Fclaude-codex\nnpm install\nnpm run build\n\n# Persist PATH + adapter pointers for non-interactive SSH:\ncat >>~\u002F.zshenv \u003C\u003C'EOF'\nexport PATH=\"$HOME\u002F.local\u002Fnpm-global\u002Fbin:$HOME\u002F.local\u002Fnode-v24.11.0-darwin-arm64\u002Fbin:$HOME\u002F.local\u002Fbin:$PATH\"\nexport CLAUDE_CODEX_ADAPTER=\"$HOME\u002Fclaude-codex\u002Fdist\u002Fsrc\u002Fadapter.mjs\"\nexport CLAUDE_CODEX_NODE=\"$HOME\u002F.local\u002Fnode-v24.11.0-darwin-arm64\u002Fbin\u002Fnode\"\n# Uncomment if api.anthropic.com is blocked from this host:\n# export ANTHROPIC_BASE_URL=\"https:\u002F\u002Fyour-anthropic-reverse-proxy.example\"\nEOF\n\ncp scripts\u002Fcodex-shim ~\u002F.local\u002Fbin\u002Fcodex && chmod +x ~\u002F.local\u002Fbin\u002Fcodex\n\nnpm run doctor   # 4 checks should all be ok\nnpm run smoke:real   # round-trips an actual Claude turn\n```\n\nAfter this, Codex App's Remote connection to the host hits `~\u002F.local\u002Fbin\u002Fcodex`\nfirst and is routed into the adapter. Disconnecting reclaims the daemon so the\nadapter exits.\n\n### Localhost GUI testing on macOS\n\nFor localhost GUI testing on macOS, the adapter can be launched by SSH and\nthe in-process TS runtime invokes the Claude Code CLI directly — no external\ndaemon to manage. Put these lightweight exports in `~\u002F.zshenv` so both login\nshells and non-interactive SSH remote commands can see the shim:\n\n```bash\nREPO=\"$HOME\u002Fpath\u002Fto\u002Fclaude-codex\" # adjust to your checkout\nexport PATH=\"$HOME\u002Fbin:$PATH\"\nexport CLAUDE_CODEX_ADAPTER=\"$REPO\u002Fdist\u002Fsrc\u002Fadapter.mjs\"\nexport CLAUDE_CODEX_NODE=\"$(command -v node)\"\nexport CLAUDE_CODEX_CLI=\"$(command -v claude)\"\nexport CODEX_REAL=\"$(command -v codex)\"\n```\n\nQuick remote probe:\n\n```bash\nssh host 'command -v codex'\nssh host 'codex --version'\nssh host '\n  set -e\n  tmp=$(mktemp -d)\n  export CODEX_HOME=\"$tmp\" CLAUDE_CODEX_MOCK=1\n  codex app-server --listen unix:\u002F\u002F >\"$tmp\u002Fdaemon.out\" 2>\"$tmp\u002Fdaemon.err\" &\n  pid=$!\n  for i in 1 2 3 4 5; do test -S \"$tmp\u002Fapp-server-control\u002Fapp-server-control.sock\" && break; sleep 0.2; done\n  test -S \"$tmp\u002Fapp-server-control\u002Fapp-server-control.sock\"\n  kill \"$pid\" 2>\u002Fdev\u002Fnull || true\n'\n```\n\nThe daemon owns the Unix socket while a Codex client is connected. When the\nlast client (`app-server proxy`) disconnects, the daemon shuts down after a\nshort idle grace period so its in-process Claude SDK runtime is reclaimed instead of\nleaking. If a turn is still active, idle shutdown is deferred until that turn\ncompletes; reconnecting\u002Fresuming the thread during that window reattaches\nnotifications to the new client peer. Codex App re-probes and restarts the\ndaemon on the next remote connection. Tune or disable this with\n`CLAUDE_CODEX_IDLE_EXIT_MS` (default `15000`; set `0` to keep the daemon\nrunning indefinitely).\n\n## Using Codex App GUI\n\n1. Install the shim and exports on the remote host as described above\n   (`~\u002Fbin\u002Fcodex`, `~\u002F.zshenv` for the localhost-GUI flow), and build the\n   adapter (`npm install && npm run build`).\n2. Open Codex App and add a Remote connection to the host (or `localhost`).\n   Codex App runs its native SSH version probe and bootstrap; the shim routes\n   `codex app-server` to this adapter.\n3. Start a new thread and send a prompt. Claude Code runs the turn: agent text\n   streams into the conversation, `Bash` calls surface as Codex command\n   approvals, and `Edit`\u002F`Write`\u002F`MultiEdit` surface as Codex file-change\n   approvals with a live diff. Approve them in the Codex App UI as usual.\n4. Disconnecting the remote in Codex App closes the proxy; once no turn is\n   active, the adapter daemon idles out and the in-process Claude SDK runtime is reclaimed\n   automatically.\n\n`npm run acceptance:gui-ssh-localhost` drives this exact path end-to-end\n(real `codex app-server` daemon + `proxy` over SSH, real Claude Code turn,\napproval bridge, and diff events) and is the closest automated check to the\nCodex App GUI Remote experience.\n\n## Modes\n\n```bash\nnode dist\u002Fsrc\u002Fadapter.mjs app-server --listen unix:\u002F\u002F\nnode dist\u002Fsrc\u002Fadapter.mjs app-server proxy\nnode dist\u002Fsrc\u002Fadapter.mjs app-server --listen stdio:\u002F\u002F\nnode dist\u002Fsrc\u002Fadapter.mjs app-server --listen ws:\u002F\u002F127.0.0.1:8788\n```\n\nSet `CLAUDE_CODEX_MOCK=1` for local protocol testing without Claude credentials.\n\n## Claude runtime knobs\n\n```bash\n# Runtime backend selection. The default uses the in-process Claude Agent SDK\n# runtime and preserves the existing Claude Code behavior.\nexport CLAUDE_CODEX_RUNTIME_TYPE=\"agent-sdk-sidecar\"\n\n# Also supported:\n#   codex             - pass app-server through to the real Codex CLI\n#   agent-http        - HTTP\u002FSSE bridge for Claude Code Channels \u002F agent-http\n#   agentapi          - HTTP\u002FSSE bridge for coder\u002Fagentapi\n#   claude-p          - one-shot PTY\u002Ftranscript wrapper via claude-p\n#   mock              - local protocol testing\n\n# Defaults surfaced through config\u002Fread and used for new threads.\nexport CLAUDE_CODEX_DEFAULT_MODEL=\"sonnet\"\nexport CLAUDE_CODEX_DEFAULT_EFFORT=\"medium\"\n\n# Optional Codex App model selector list. Accepts comma-separated ids or a JSON\n# array of ids\u002Fobjects: [{\"id\":\"sonnet\",\"displayName\":\"Claude Sonnet\"}].\nexport CLAUDE_CODEX_MODELS=\"sonnet,opus,haiku,sonnet-1m,opus-plan\"\n\n# Map Codex++ UI ids to Claude Code SDK model aliases\u002Ffull model names.\nexport CLAUDE_CODEX_MODEL_ALIASES='{\"my-sonnet\":\"sonnet\",\"my-long-context\":\"sonnet[1m]\"}'\n\n# Map Codex-safe effort values to Claude SDK effort values. For example, keep\n# the wire protocol at xhigh while asking Claude Code for its max effort.\nexport CLAUDE_CODEX_EFFORT_ALIASES='{\"xhigh\":\"max\"}'\n\n# JSON object or path to a JSON file. Passed to ClaudeAgentOptions.mcp_servers.\nexport CLAUDE_CODEX_MCP_SERVERS='{\"github\":{\"type\":\"stdio\",\"command\":\"github-mcp\"}}'\n\n# Pre-approved tools. Other tools still route through Codex approval.\nexport CLAUDE_CODEX_ALLOWED_TOOLS=\"Read,Glob,Grep\"\n\n# Extra directories exposed to Claude Agent SDK.\nexport CLAUDE_CODEX_ADD_DIRS=\"\u002Frepo\u002Fshared,\u002Frepo\u002Fdocs\"\n\n# Ask Claude Agent SDK to enable file checkpointing.\nexport CLAUDE_CODEX_ENABLE_FILE_CHECKPOINTING=1\n\n# Optional per-thread git worktree isolation.\nexport CLAUDE_CODEX_AUTO_WORKTREE=1\nexport CLAUDE_CODEX_WORKTREE_ROOT=\"$HOME\u002F.claude-codex\u002Fworktrees\"\n```\n\n### Alternative Claude Code backends\n\nThe adapter's internal Codex protocol layer talks to a small `ClaudeRuntime`\ninterface, so non-SDK Claude Code bridges can be selected without removing the\nexisting Agent SDK route.\n\nCodex App's model menu remains a model selector only. Pick `Claude Sonnet`,\n`Claude Opus`, `Claude Haiku`, etc. there; the active Claude Code connection\nroute is selected outside the App with the remote shim mode.\n\nIf you install `scripts\u002Fcodex-shim` earlier in `PATH`, it acts as a router. Set\n`CODEX_REAL` to the real Codex CLI path and put per-host routing in\n`~\u002F.claude-codex\u002Fruntime.env`:\n\n```bash\n# Keep native Codex behavior for Codex App Remote.\nexport CLAUDE_CODEX_RUNTIME_TYPE=\"codex\"\nexport CODEX_REAL=\"\u002Fabsolute\u002Fpath\u002Fto\u002Freal\u002Fcodex\"\n```\n\nNon-`app-server` commands are always forwarded to the real Codex CLI when one is\navailable, so the shim can coexist with normal command-line Codex usage.\n\nNative Codex passthrough is different from the four Claude backends: in\n`CLAUDE_CODEX_RUNTIME_TYPE=codex` the shim launches the real Codex app-server,\nso the adapter is not in the process and cannot dynamically switch back from any\nin-App control. Switch that mode with the host helper (for example\n`claude-codex-mode set codex` or `claude-codex-mode set agent-sdk-sidecar`) and\nreconnect the Remote session.\n\nInstall the helper next to the shim:\n\n```bash\ninstall -m 0755 scripts\u002Fclaude-codex-mode ~\u002F.local\u002Fbin\u002Fclaude-codex-mode\n```\n\nIt rewrites `~\u002F.claude-codex\u002Fruntime.env`, prepares the matching bridge daemon\nfor `agent-http` or `agentapi`, stops the current app-server so Codex App will\nreconnect into the new route, and provides readback commands:\n\n```bash\nclaude-codex-mode list         # all selectable modes; current one is marked *\nclaude-codex-mode set agent-http\nclaude-codex-mode set agent-http opus  # switch route and restart bridge with Opus\nclaude-codex-mode set agent-http opus \u002Frepo\u002Fapp  # optional explicit bridge cwd\nclaude-codex-mode model opus           # keep current route; update default\u002Fbridge model\nclaude-codex-mode ensure-bridge agent-http opus \u002Frepo\u002Fapp # bridge only; no adapter restart\nclaude-codex-mode trust                # accept Claude Code trust prompt for agentapi\nclaude-codex-mode help         # also -h \u002F --help\nclaude-codex-mode status       # current mode, bridge health, last runtime logs\nclaude-codex-mode read         # alias for status\nclaude-codex-mode last-turn    # last runtime.turn.select JSON line\nclaude-codex-mode last-user-turn # last user-visible turn; skips title\u002Fsummary turns\nclaude-codex-mode logs adapter\nclaude-codex-mode logs agent-http\nclaude-codex-mode logs agentapi\n```\n\nModel switching is exact per turn for the SDK runtime and `claude-p`, because\nthe adapter can pass `model` to those backends. For `agent-http` and `agentapi`,\nthe HTTP bridge talks to a long-lived interactive Claude Code session; the safe\nway to change the model is to restart that bridge with `claude --model \u003Calias>`\nvia `claude-codex-mode model \u003Calias>` or `claude-codex-mode set \u003Cmode> \u003Calias>`.\nThe adapter also prepares managed HTTP bridges per turn with the thread cwd, so\nthe long-lived Claude Code process is relaunched in the current Codex App\nworkspace when needed. `claude-codex-mode read` shows the configured bridge cwd\nand every running pooled bridge's cwd\u002Fmodel\u002Fport.\nWhen using `agentapi`, the helper also detects Claude Code's workspace trust\nprompt and tells you to run `claude-codex-mode trust` after reviewing the path.\n\n#### agent-http \u002F Channels\n\nSet the mode through the helper. It loads the Channels bridge implementation\nfrom `$CLAUDE_CODEX_AGENT_HTTP_DIR` or `~\u002Fagent-http`, but launches Claude Code\nfrom the Codex App thread cwd. The helper writes an absolute MCP config under\nthe matching bridge pool directory, so the channel server can be loaded even\nwhen Claude Code's process cwd is your project rather than the bridge checkout:\n\n```bash\nclaude-codex-mode set agent-http opus\n```\n\nThe backend uses `POST \u002Fmessage`, `GET \u002Fmessages`, `GET \u002Fstatus`, and\n`GET \u002Fevents` when available. It streams message-level deltas into Codex; it\ndoes not expose Agent SDK-level tool-use, thinking, or permission events.\n\n#### agentapi\n\nSet the mode through the helper. It starts `agentapi server --type=claude` from\nthe Codex App thread cwd and points the adapter at its HTTP API:\n\n```bash\nclaude-codex-mode set agentapi opus\n```\n\nThis is useful for quickly reusing an existing terminal-backed Claude Code\nsession. The adapter consumes agentapi's HTTP\u002FSSE message stream and maps final\nagent text into Codex messages. Rich Codex approval\u002Ffile-change events are not\navailable because agentapi exposes terminal-derived text, not semantic tool\nevents.\n\n#### claude-p\n\nInstall `claude-p` somewhere on the remote host and select the one-shot\ntranscript backend:\n\n```bash\nexport CLAUDE_CODEX_RUNTIME_TYPE=\"claude-p\"\nexport CLAUDE_CODEX_CLAUDE_P_COMMAND=\"claude-p\"\n# For npx-style launch:\n# export CLAUDE_CODEX_CLAUDE_P_COMMAND=\"npx\"\n# export CLAUDE_CODEX_CLAUDE_P_ARGS='[\"claude-p\"]'\n# Keep claude-p one-shot by default. Set to 1 only after verifying your\n# claude-p build handles --resume + --input-file correctly.\n# export CLAUDE_CODEX_CLAUDE_P_RESUME=0\n```\n\nThis backend runs `claude-p --output-format json --input-file ...` for each\nturn, emits the final assistant text, and stores `claude-p:\u003Csession_id>` for\ndiagnostics when the wrapper reports one. It is not a true streaming backend,\ndoes not support `turn\u002Fsteer`, and defaults to one-shot turns instead of resume\nbecause current `claude-p` builds can replay the previous result when combining\n`--resume` with `--input-file`.\n\n`CLAUDE_CODEX_AUTO_WORKTREE` is off by default because it creates branches and\nworktrees in the target repository. When enabled, new Codex threads run in a\ndedicated `git worktree`.\n\n## Protocol coverage\n\nImplemented as real remote\u002Fruntime behavior:\n\n- Codex app-server v2 transports: stdio, WebSocket, Unix socket daemon, and\n  `app-server proxy` raw stdio forwarding.\n- Core thread lifecycle: start, resume, fork, list, read, turns list, name,\n  archive\u002Funarchive, unsubscribe, interrupt.\n- Claude Code runtime: `ClaudeSDKClient.query`, session resume, fork session,\n  partial text streaming, interrupt, MCP server config, allowed tools, add dirs,\n  and file checkpointing flags.\n- Approval bridge: Claude `Bash` maps to Codex command approval, and\n  `Edit`\u002F`Write`\u002F`MultiEdit` map to Codex file-change approval.\n- Stream bridge: turn started\u002Fcompleted, thread status changes, agent text\n  deltas, reasoning deltas, command output deltas, file patches, generic tool\n  item completion, and aggregated git diff updates.\n- Remote utilities: file read\u002Fwrite\u002Flist\u002Fmetadata\u002Fcopy\u002Fremove\u002Fwatch, command\n  exec with stdin\u002Fterminate, process spawn\u002Fstdin\u002Fkill, fuzzy file search, direct\n  MCP stdio\u002FHTTP tool and resource calls.\n- Optional per-thread git worktree isolation.\n\nCompatibility-only app UI methods return stable empty or inert responses when\nthey are OpenAI-account\u002Fplugin-marketplace\u002Frealtime-specific rather than Claude\nCode runtime capabilities. Examples: marketplace install\u002Fupdate, OpenAI account\nlogin\u002Flogout, realtime audio, and Windows sandbox setup. Claude VS Code is used\nas an interaction reference only; this adapter does not call its private RPC.\n\n## Validation\n\n```bash\nnpm test\nnpm run doctor\nnpm run probe:codex-cli-remote # probes current local codex --remote behavior\nnpm run smoke:real # requires ANTHROPIC_API_KEY, Bedrock, or Vertex auth\nnpm run acceptance:local-remote # full local Remote shim\u002Fdaemon\u002Fproxy + real Claude file edit\nnpm run acceptance:gui-ssh-localhost # SSH localhost -> login shell -> shim -> GUI-session Claude runtime\n.\u002Fscripts\u002Fcodex-shim --version\nCLAUDE_CODEX_ADAPTER=\"$PWD\u002Fdist\u002Fsrc\u002Fadapter.mjs\" .\u002Fscripts\u002Fcodex-shim app-server --help\n```\n\n`acceptance:local-remote` creates an ignored `.claude-codex\u002Flocal-remote-acceptance-*`\ndirectory, installs the shim into a temporary PATH, starts the Unix socket\ndaemon, connects through `app-server proxy`, auto-approves Claude Code file\nedits, and verifies that Claude creates a file in the temporary workspace.\n\n`probe:codex-cli-remote` starts the adapter in mock WebSocket mode and then\ntries the currently installed `codex --remote ws:\u002F\u002F...` CLI. It keeps a\ntranscript under `.claude-codex\u002Fcodex-cli-remote-probe-*` by default. In a\ndesktop flow the app supplies its own interactive\u002Fauth context; the CLI probe\nreports `blocked-login`, `blocked-timeout`, or `blocked-no-tty` when the local\nCLI cannot complete an automated remote prompt because it stops at those local\ngates first.\n\n`acceptance:gui-ssh-localhost` is the closest automated check to Codex App GUI\nRemote on the current Mac: it starts `codex app-server --listen unix:\u002F\u002F` and\n`codex app-server proxy` through `ssh localhost 'zsh -lc ...'`, then verifies\nClaude Code can edit a git workspace through Codex approval and diff events.\n","该项目是一个远程模式适配器，允许Codex桌面应用程序通过原生的Codex `app-server`协议与Claude Code进行通信。其核心功能是通过在远程SSH主机上部署一个`codex`垫片来实现Codex App与Claude Code之间的交互，同时支持Node.js 24+以确保稳定运行，并使用了`@anthropic-ai\u002Fclaude-agent-sdk`作为Claude的主要运行时依赖。适用于需要在远程服务器上利用Claude AI的能力进行开发或自动化任务的场景，尤其是当直接访问Anthropic API受到限制时，可通过设置环境变量绕过这些限制，保持原有CLI认证方式不变。",2,"2026-06-11 04:00:40","CREATED_QUERY"]