@gkorepanov/ccodex 0.3.0

package/BUILD_BENCHMARKS.md

@@ -0,0 +1,27 @@
+# Build benchmarks
+
+Measured on 2026-07-15 on an Apple Silicon Mac with Rust `1.95.0`, Node `24.14.0`, npm `11.9.0`, and the pinned Codex `0.144.4` dependency graph.
+
+| Build | Condition | Wall time |
+|---|---|---:|
+| Native relay, `aarch64-apple-darwin` | Empty target cache for this target | 17m 21s |
+| Native relay, `aarch64-apple-darwin` | `relay/src/main.rs` touched; dependency artifacts retained | 2m 22.92s |
+| TypeScript | `dist/` removed | 1.92s |
+| TypeScript | One source touched; current non-incremental `tsc` configuration | 1.92s |
+
+The representative Rust edit rebuild is **7.28× faster** than the clean relay build. Most of its remaining 2m 23s is ThinLTO relinking the large pinned Codex dependency graph. TypeScript currently performs a full compile on every invocation, but at under two seconds an incremental project cache would add complexity without material developer benefit.
+
+Commands:
+
+```sh
+CCODEX_RELAY_TARGET=aarch64-apple-darwin ./scripts/build-relay.sh
+touch relay/src/main.rs
+CCODEX_RELAY_TARGET=aarch64-apple-darwin ./scripts/build-relay.sh
+
+rm -rf dist
+npm run build:ts
+touch src/management/setup.ts
+npm run build:ts
+```
+
+The Linux x64 Docker/QEMU cold build took **1h 53m 12.37s** (`real 6792.37s`). It is intentionally excluded from the clean-vs-edit comparison because emulation and image/cache download time measure the local container environment rather than CCodex compilation; GitHub release builds run natively on x64/arm64 Linux runners.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Korepanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES.md

@@ -0,0 +1,11 @@
+# Distribution and third-party terms
+
+Project-owned CCodex source is distributed under the MIT License in `LICENSE`.
+
+- OpenAI Codex `0.144.4` is used and linked under Apache-2.0. The exact upstream revision is recorded in `compatibility.json`.
+- Claude Agent SDK `0.3.209` is installed from Anthropic's npm package as an exact runtime dependency; CCodex does not copy or rehost its platform binaries. Use remains subject to Anthropic's applicable legal agreements.
+- Each user authenticates locally with their own Codex and Claude Code sessions. CCodex does not collect, proxy, share, or bundle provider credentials.
+- Provider authentication and subscription policies can change independently of CCodex. Compatibility with a current login flow is not a guarantee of future provider support.
+- `THIRD_PARTY_NOTICES.md`, the npm/Cargo SBOMs, and release checksums are generated from the exact lockfiles for every release.
+
+CCodex is independent and unofficial. It is not affiliated with or endorsed by OpenAI or Anthropic. Codex, Claude, and related marks belong to their respective owners.

package/README.md

@@ -0,0 +1,102 @@
+# CCodex
+
+> An independent, unofficial compatibility bridge. Not affiliated with or endorsed by OpenAI or Anthropic. Codex, Claude, and related marks belong to their respective owners.
+
+CCodex lets Codex App use both native Codex models and Claude Code models. It owns the SSH-side `codex app-server` command, preserves Codex App's thread/turn/tool/approval lifecycle, and delegates ordinary non-app-server Codex commands to the user's global Codex CLI.
+
+Compatibility is intentionally fail-closed: CCodex `0.3.0` embeds Codex CLI `0.144.4`, Claude Agent SDK `0.3.209`, Claude Code `2.1.209`, and requires Node.js `>=22.13 <27` plus npm `>=10`.
+
+## Install
+
+Both Codex and Claude must already be logged in. Installing a newer global Codex later does not replace CCodex's app-server runtime.
+
+```sh
+npm install -g @gkorepanov/ccodex
+ccodex setup
+```
+
+Or with the bootstrap script attached to the latest GitHub release:
+
+```sh
+curl -fsSL https://github.com/gkorepanov/ccodex/releases/latest/download/install.sh | sh
+```
+
+`setup` validates the platform, exact provider runtimes, relay binary, both logins, and a no-charge gateway startup before atomically activating `~/.ccodex/current`. It installs `~/.ccodex/bin/codex` ahead of npm's global bin in Bash, Zsh, and Fish.
+
+If authentication is missing:
+
+```sh
+ccodex auth codex
+ccodex auth claude
+ccodex setup
+```
+
+## Lifecycle
+
+```sh
+ccodex doctor
+ccodex doctor --json
+ccodex update --check
+ccodex update                  # npm latest
+ccodex update --channel next
+ccodex rollback
+ccodex uninstall              # preserves config, state, and captures
+ccodex uninstall --purge --yes
+```
+
+The release asset provides the same state-preserving uninstall without relying on the current shell `PATH`:
+
+```sh
+curl -fsSL https://github.com/gkorepanov/ccodex/releases/latest/download/uninstall.sh | sh
+```
+
+The managed layout is versioned and transactional:
+
+```text
+~/.ccodex/
+├── bin/{codex,ccodex}
+├── current -> versions/0.3.0
+├── previous -> versions/<previous>
+├── versions/
+├── staging/
+├── install.json
+└── state/
+```
+
+Install/update failures leave the old `current` and daemon active. If readiness fails after switching, CCodex restores `previous`. Uninstall removes only exact owned shell blocks and unmodified shims; modified files are reported and preserved.
+
+## Codex App behavior
+
+- `codex app-server`, `proxy`, and `daemon ...` always use the pinned CCodex runtime.
+- Native `gpt-*` models remain stock Codex models; `claude:*` entries use Claude Code.
+- Claude effort and fast mode map from Codex reasoning/priority settings.
+- Provider changes use explicit Fork with compact handoff. Same-provider model changes remain in-place.
+- Bridge notices start with `⚙️ CCodex`; exact thread failures start with `⚠️ CCodex ERROR`.
+- Full Access maps to Claude `bypassPermissions`, Ask for approval to `default`, and Approve for me to Claude `auto`.
+- RPC capture is enabled by default under `~/.ccodex/state`, rolls at a combined 1 GiB, uses mode `0600`, and includes prompts/outputs unless configured otherwise.
+
+The exact SSH post-install checks are in [SSH_VERIFY.md](./SSH_VERIFY.md).
+
+## Supported targets
+
+- macOS 11+ on arm64 and x64
+- Linux arm64 and x64 with glibc >=2.31 (Ubuntu 22.04+, Debian 11+, Fedora/RHEL equivalents); Alpine/musl is not supported
+- Bash, Zsh, and Fish
+
+Each target receives a separate `@gkorepanov/ccodex-relay-*` optional package. Public installation never compiles Rust or native Node addons.
+
+## Development and release gates
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run test:contracts
+npm run test:public-package
+```
+
+Release workflows build and execute all four native relay packages, publish platform packages before the main package, generate checksums/SBOM/notices, and use npm trusted publishing with provenance.
+
+First publication and later release commands are documented in [RELEASING.md](./RELEASING.md); measured clean/edit build times are in [BUILD_BENCHMARKS.md](./BUILD_BENCHMARKS.md).
+
+CCodex is MIT-licensed. Provider and third-party terms are summarized in [LICENSES.md](./LICENSES.md), and the release workflow enforces matching licenses and generated notices.

package/RELEASING.md

@@ -0,0 +1,98 @@
+# Releasing CCodex
+
+The five npm names (`@gkorepanov/ccodex` plus four platform relay packages) were unoccupied when checked on 2026-07-15.
+
+## License gate
+
+CCodex `0.3.0` uses MIT in the main package and all four relay packages. Provider terms and generated third-party notices are recorded in `LICENSES.md` and `THIRD_PARTY_NOTICES.md`. Require this command to pass before every upload:
+
+```sh
+node release/legal-gate.mjs
+```
+
+## First publication
+
+An npm trusted publisher cannot be configured until each package exists. Bootstrap the five packages once from an npm-authenticated workstation:
+
+```sh
+npm login
+npm whoami                         # must print gkorepanov
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run test:contracts
+npm run test:public-package
+node release/legal-gate.mjs
+```
+
+Build all four platform binaries through the release matrix or place its verified artifacts under the matching `packages/relay-*/bin/ccodex-relay`, then pack:
+
+```sh
+rm -rf release-artifacts
+mkdir release-artifacts
+for package in \
+  packages/relay-darwin-arm64 \
+  packages/relay-darwin-x64 \
+  packages/relay-linux-arm64-gnu \
+  packages/relay-linux-x64-gnu; do
+  npm pack "./$package" --pack-destination release-artifacts
+done
+npm pack --pack-destination release-artifacts
+node release/generate-manifest.mjs release-artifacts
+shasum -a 256 -c release-artifacts/SHA256SUMS
+```
+
+Publish platform packages first and the main package last, initially on `next`:
+
+```sh
+for package in release-artifacts/gkorepanov-ccodex-relay-*.tgz; do
+  npm publish "$package" --access public --tag next --provenance=false
+done
+npm publish release-artifacts/gkorepanov-ccodex-0.3.0.tgz --access public --tag next --provenance=false
+```
+
+`--provenance=false` is only for this one-time local bootstrap: npm cannot create GitHub OIDC provenance before the packages exist and have trusted publishers configured. Later workflow releases keep provenance enabled.
+
+Acceptance test:
+
+```sh
+npm install -g @gkorepanov/ccodex@next
+ccodex setup
+ccodex doctor --deep
+```
+
+Promote all five packages in dependency-safe order:
+
+```sh
+npm run release:promote -- 0.3.0          # dry run
+npm run release:promote -- 0.3.0 --execute
+```
+
+## Trusted publishing for later releases
+
+For every package, configure the npm trusted publisher with:
+
+- GitHub owner: `gkorepanov`
+- repository: `ccodex` (or the final repository name)
+- workflow: `release.yml`
+- GitHub environment: `npm`
+
+Create the matching protected `npm` environment in GitHub. The workflow uses npm OIDC, publishes relay packages before the main package, emits npm provenance, generates npm/Cargo SBOMs and notices, signs build provenance, and attaches immutable metadata to the GitHub release.
+
+For each later release:
+
+```sh
+npm run release:version -- 0.3.1
+npm run check
+npm test
+npm run test:contracts
+npm run test:public-package
+git add -A
+git commit -m 'Release 0.3.1'
+git tag v0.3.1
+git push origin main v0.3.1
+```
+
+Tag builds publish to `next`. Run the acceptance test and then `release:promote --execute`. Never republish an existing version; npm versions are immutable.
+
+The GitHub release also publishes stable `install.sh` and `uninstall.sh` assets used by the README one-liners.

package/SSH_VERIFY.md

@@ -0,0 +1,69 @@
+# SSH install and verification
+
+These are the user-run post-release checks for a macOS/Linux SSH host. A standalone Codex installation is neither required nor used.
+
+## 1. Prerequisites
+
+```sh
+node --version                   # >=22.13 <27
+npm --version                    # >=10
+npx --yes @openai/codex@0.144.4 login status
+claude auth status --json
+```
+
+If either login is missing, complete the official login before setup.
+
+## 2. Install and own `codex app-server`
+
+```sh
+npm install -g @gkorepanov/ccodex
+ccodex setup
+exec "$SHELL" -l
+command -v ccodex
+command -v codex
+ccodex doctor
+```
+
+Both commands must resolve under `~/.ccodex/bin`. CCodex embeds its tested app-server Codex; a separately installed `@openai/codex@latest` is used only for ordinary CLI delegation.
+
+To prove global Codex upgrades cannot bypass the bridge:
+
+```sh
+npm install -g @openai/codex@latest
+exec "$SHELL" -l
+command -v codex                 # still ~/.ccodex/bin/codex
+ccodex doctor                    # pinned app-server remains 0.144.4
+```
+
+## 3. Bootstrap remote control
+
+```sh
+codex app-server daemon bootstrap --remote-control
+codex app-server daemon version
+```
+
+The JSON reports `backend:"pid"`, `autoUpdateEnabled:false`, `remoteControlEnabled:true`, and app-server version `0.144.4`.
+
+## 4. Verify the Codex App transport
+
+From a source checkout, the catalog-only probe uses the exact proxy transport used by Codex App:
+
+```sh
+CCODEX_PROXY_COMMAND='codex app-server proxy' \
+CCODEX_PROBE_CWD="$HOME" \
+CCODEX_CATALOG_ONLY=1 \
+node scripts/probe-proxy.mjs
+```
+
+Acceptance output contains `proxyTransport:true`, `stockModels > 0`, and `claudeModels > 0`. This creates no model turn. Reconnect the SSH environment in Codex App and perform the final UI smoke manually.
+
+## Update, rollback, uninstall
+
+```sh
+ccodex update --check
+ccodex update
+ccodex rollback
+ccodex uninstall                # state stays in ~/.ccodex/state
+```
+
+`ccodex uninstall --purge --yes` additionally deletes config, captures, and state. Modified shell blocks or shims are preserved and reported rather than overwritten.