cxstatusline 0.1.1 → 0.3.0

package/README.md

@@ -37,12 +37,11 @@ Independent project; not an official OpenAI product.
 
 ## Requirements
 
-- **macOS 14 (Sonoma) or newer** on Apple Silicon (`darwin-arm64`) or Intel (`darwin-x64`). Clean-macOS-14 acceptance is unproven and evidenced only by build metadata (`MACOSX_DEPLOYMENT_TARGET=14.0`, `vtool` `minos`, and system-only `otool -L` linkage).
+- **macOS 14 (Sonoma) or newer** (Apple Silicon or Intel).
 - **Node.js 22+**.
-- **Stock Codex CLI install** kept in place (`~/.codex/` and original launcher).
+- **Existing Codex CLI installation** kept in place (`~/.codex/`).
 - **Git**.
-- **Bun 1.4+** is required only for building/linking from a git checkout.
-- **Rust toolchain** (1.95.0+) is required only for `cxstatusline install --compile`.
+- **Rust toolchain** (1.95.0+) is required only if building from source (`--compile`).
 
 ## 🚀 Install
 
@@ -54,7 +53,7 @@ cxstatusline install
 cxstatusline doctor
 ```
 
-`install` downloads the release matching your exact Codex version and CPU, verifies every byte against `manifest.json`, and activates it. Nothing is signed or notarized; see [Security and trust](#security-and-trust).
+`install` downloads the verified prebuilt binary matching your exact Codex version and architecture, verifies checksums against `manifest.json`, and activates it.
 
 Start Codex, accept its cxstatusline hook trust prompt, and open a new session after installation. An already-running process does not switch binaries when installation finishes.
 
@@ -110,14 +109,14 @@ it never opens the TUI.
 ## Update
 
 ```sh
-codex update
-# or
 cxstatusline update
 ```
 
-`codex update` (or `cxstatusline update`) runs Codex's upstream updater, then downloads the matching prebuilt; never compiles.
+`cxstatusline update` runs a pre-flight check: if upstream Codex has a new version but prebuilts have not yet been published, it warns and stops before touching your active installation.
 
-If no verified prebuilt release exists for the new version, cxstatusline fails closed: the working pair is left in place and the command says so. The SessionStart hook retries daily according to update policy.
+Options:
+- `cxstatusline update --compile`: updates upstream Codex and compiles the statusline from source for the new version.
+- `cxstatusline update --force`: updates upstream Codex to stock immediately, even if prebuilt binaries are not yet published.
 
 ## Revert
 
@@ -127,43 +126,35 @@ cxstatusline revert
 
 `cxstatusline revert` restores the stock launcher, removes CX-owned executables, generations, and the hook, and keeps settings and source. Generations are kept until revert; close Codex sessions first.
 
-## How it works
-
-**Renderer and settings:** The statusline is powered by a Node CLI renderer that receives session metadata from Codex, formats ANSI rows according to your `settings.json`, and writes the footer.
-
-**The additive Rust patch:** Because the Codex CLI does not yet provide an external statusline hook ([openai/codex#17827](https://github.com/openai/codex/issues/17827)), cxstatusline applies a minimal additive patch to `codex-tui` and builds synchronized binaries (`codex` and companion `codex-code-mode-host`). The patch invokes the local renderer without altering Codex's networking or command evaluation.
-
-**Generations and atomic activation:** Each verified pair installs into an immutable generation directory under `~/.local/libexec/cxstatusline/generations/<id>/`. An atomic rename switches the `~/.local/libexec/cxstatusline/current` symlink. The wrapper in `~/.local/bin/codex` resolves `current` once before execution, ensuring running sessions and their companion host stay locked to the same generation. Previous generations accumulate until explicit `cxstatusline revert`.
-
-**SessionStart hook and update policy:** A hook registered in Codex's `hooks.json` checks for upstream version drift on session start. When drift is detected, a detached child process downloads the matching prebuilt release without interrupting your active terminal session.
-
+## 🔍 How it works
+ 
+Codex CLI does not yet provide a native statusline extension hook ([openai/codex#17827](https://github.com/openai/codex/issues/17827)). `cxstatusline` bridges this with a lightweight additive Rust patch that captures session telemetry (model, context tokens, Git branch, rate limits) and invokes a local Node/TypeScript ANSI renderer.
+ 
+Updates use an immutable **generation-based layout** (`~/.local/libexec/cxstatusline/generations/`) with atomic symlink swaps, ensuring your active terminal sessions are never interrupted.
+ 
+👉 For a full architectural breakdown of how Codex is patched with Rust, check out the **[Architecture & Technical Deep Dive (wiki.md)](wiki.md)**.
+ 
 ## Supported versions
-
-cxstatusline matches exact stable releases. Supported versions in `patches/manifest.json`:
-- **0.152.1**
+ 
+cxstatusline matches exact stable releases. Supported versions:
+- **0.154.0**
+- **0.153.4**
 - **0.153.0**
-- **0.153.4** (candidate)
-
+- **0.152.1**
+ 
 If your Codex version is not listed, cxstatusline fails closed: it will neither download an unverified prebuilt nor attempt source compilation. New versions require a tested patch file, an entry in `patches/manifest.json`, and a release workflow run.
-
+ 
 ## 🩺 Troubleshooting
-
+ 
 - **No footer:** Run `cxstatusline doctor`, verify `which codex` points to `~/.local/bin/codex`, check your `PATH`, accept the hook prompt in Codex, and start a fresh session.
 - **Unsupported version:** Wait for an explicitly supported patch. `--force` does not bypass version compatibility. Keep a working stock Codex installation.
 - **Failed build:** Inspect `~/.local/state/cxstatusline/patch.log`, fix the prerequisite, then run `cxstatusline patch --force`. Redact personal paths, session identifiers, and secrets before sharing logs.
 - **Missing companion / interrupted install:** Run `cxstatusline doctor`. Use `cxstatusline revert` to return to stock before reinstalling if unhealthy. Do not manually replace only one binary.
-
-## Security and trust
-
-- **Unsigned and unnotarized:** cxstatusline binaries are not signed or notarized by Apple; macOS Gatekeeper warnings are expected. Do not disable Gatekeeper globally; clear the quarantine attribute for these two files only, or build from source with `install --compile`.
-- **Integrity vs. identity:** Checksums and manifests prove integrity relative to the GitHub release, not publisher identity.
-- **Archive contents:** Each prebuilt release archive contains exactly five files: `codex`, `codex-code-mode-host`, upstream `LICENSE` (Apache-2.0), upstream `NOTICE`, and `THIRD_PARTY_NOTICES.md` (combining cxstatusline notices and generated Rust dependency notices). No extra directories, files, or telemetry.
-- **Security policy:** See [SECURITY.md](SECURITY.md) for full trust boundaries, file layout, and vulnerability reporting.
-
-## Contributing and license
-
-See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CHANGELOG.md](CHANGELOG.md).
-
-Inspired by [ccstatusline](https://github.com/sirmalloc/ccstatusline) for Claude Code. Its renderer and configuration UI are adapted here for Codex. Thanks to its creators and contributors!
-
-cxstatusline is [MIT licensed](LICENSE). [NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) preserve upstream attribution. The build includes dependency license texts in `dist/THIRD_PARTY_LICENSES.txt`. OpenAI Codex remains separately licensed under Apache-2.0.
+ 
+## 🙏 Acknowledgments
+ 
+Huge shout-out to **[ccstatusline](https://github.com/sirmalloc/ccstatusline)** by [@sirmalloc](https://github.com/sirmalloc)! The interactive configurator TUI, widget architecture, Powerline themes, and overall statusline UX in `cxstatusline` are directly adapted and inspired by `ccstatusline`'s fantastic work for Claude Code.
+ 
+## License
+ 
+cxstatusline is [MIT licensed](LICENSE). See [SECURITY.md](SECURITY.md) for security boundaries and reporting. [NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) preserve upstream attribution. OpenAI Codex remains separately licensed under Apache-2.0.