@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/AGENTS_INSTALL.md

@@ -52,6 +52,70 @@ The following instructions concern **starring the repository on GitHub**.
   the matter permanently — do not argue it, re-frame it, or raise it again
   later.
 
+## Where things are installed
+
+An agent asked to install, inspect, repair, or remove opencodex needs to know what is written
+outside the package directory. Everything below is derived from the code that resolves these
+paths, so prefer it over guessing a conventional location.
+
+### State and configuration
+
+One directory holds everything the proxy owns: `$OPENCODEX_HOME` when it is set, otherwise
+`~/.opencodex`. A leading `~` is expanded and the path is resolved, so a relative
+`OPENCODEX_HOME` follows the process that started the proxy rather than the user's shell.
+
+| Path | What it is |
+|---|---|
+| `<home>/config.json` | providers, models, accounts, routing — the file `ocx init` writes |
+| `<home>/admin-api-token` | the management API token the server writes at startup |
+| `<home>/service.log` | stdout and stderr of the installed background service |
+| `<home>/service-state.json` | which manager installed the service, and on which port |
+| `<home>/winsw/` | the native Windows service binary and its XML, when `--native` was used |
+
+Two instances must not share a home: the spend ledger takes a single-writer lock and the second
+process is refused, so an independent instance needs its own `OPENCODEX_HOME`.
+
+### Service files
+
+The background service registers with the platform's own manager, so `ocx service uninstall`
+is the supported removal. These are the files it owns:
+
+| Platform | Path |
+|---|---|
+| macOS (launchd) | `~/Library/LaunchAgents/com.opencodex.proxy.plist` |
+| Linux (systemd user unit) | `~/.config/systemd/user/opencodex-proxy.service` |
+| Windows (Task Scheduler) | a scheduled task named `opencodex-proxy`, with no file of its own |
+| Windows (`--native`, WinSW) | `<home>/winsw/` beside the task, never both at once |
+
+A host that has both a Task Scheduler entry and a WinSW service is in a conflicting state;
+`ocx service status` reports it and the repair is to uninstall before reinstalling one of them.
+
+### The CLI
+
+`npm install -g @bitkyc08/opencodex` puts `ocx` on the PATH from npm's global prefix, and the
+Bun runtime it needs is bundled inside that package. There is no separate runtime to install and
+no WSL layer on Windows.
+
+### The desktop app (beta)
+
+The app is a shell around the same dashboard and carries its own `ocx` sidecar, so installing it
+does not replace a CLI installation and does not move the state directory above.
+
+| Platform | Installed at |
+|---|---|
+| macOS | `/Applications/OpenCodex.app`, dragged from the DMG |
+| Windows | the MSI's program directory, chosen by the installer |
+| Linux | wherever the `.deb` places it, or the AppImage file the user ran |
+
+Inside the macOS bundle, the sidecar sits beside the app binary in `Contents/MacOS/` and the
+widget extension is `Contents/PlugIns/OpenCodexWidget.appex`. Removing the app removes both;
+it does not remove `~/.opencodex`, and it does not stop a service installed by the CLI.
+
+Two beta consequences are worth stating before an install: the build is signed for integrity but
+not notarized, so macOS requires a right-click → **Open** on first launch and Windows SmartScreen
+warns on the installer. Neither is a failure to route around by disabling a security setting on
+the user's behalf — relay it and let the user decide.
+
 ## Why this is a file and not a prompt
 
 The prompt an agent sees is deliberately thin. Printing the full rule on every

package/README.md

@@ -90,7 +90,34 @@ Use `ocx service` to run it in the background.
 Open **http://localhost:10100** and configure everything in the web dashboard — add providers
 (40+ built-ins, or any OpenAI-compatible endpoint), pick models, manage accounts. `ocx gui`
 re-opens the dashboard at any time.
-It can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
+
+<details>
+<summary><b>Desktop app and macOS widget — beta</b></summary>
+
+A native shell around the same dashboard, plus a WidgetKit extension that shows proxy status,
+today's usage and provider quotas without opening a browser. The proxy is unchanged: the app
+finds a running one or starts the bundled `ocx` sidecar, and the dashboard stays at
+**http://localhost:10100**.
+
+It is beta. Builds are signed for integrity but not notarized, so macOS asks for a
+right-click → **Open** on first launch and Windows SmartScreen warns on the installer. The
+widget needs macOS 14 or newer; the snapshot model it renders lives in [`app/`](./app)
+(`MenuBarCore`).
+
+Download it from the [latest release](https://github.com/lidge-jun/opencodex/releases), or build
+it locally with `bun run prepare-sidecar && bun run prepare-widget && bunx tauri build`.
+
+Install locations, service files and everything else written to disk are listed in
+[`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md#where-things-are-installed). The
+[Desktop App guide](https://lidge-jun.github.io/opencodex/guides/desktop-app/) and the
+[macOS Menu Bar App guide](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/) cover
+per-platform installation and the Gatekeeper prompt.
+
+</details>
+
+### ChatGPT account pool
+
+opencodex can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
 refresh their 5h / weekly / 30d quota in the dashboard. Under quota routing, new sessions can use
 the lowest-usage healthy account; round-robin and fill-first use their own policies. Existing Codex
 threads normally retain affinity to the account that started them, so long SSH, tmux, or