impel-cli 0.7.0

package/README.md

@@ -0,0 +1,695 @@
+# impel
+
+A tiny, dependency-free CLI for macOS, Linux, and Windows that switches your
+local **Claude Code** and **Codex** between two modes, per tool, reversibly:
+
+- **gateway mode** — route through Impel's custom gateway, authenticated with an
+  Impel Personal Access Token (PAT).
+- **account mode** — your own normal Anthropic / OpenAI login.
+
+The gateway accepts `Authorization: Bearer impel_pat_...` directly. `impel` stores
+that PAT locally and hands it to both tools through the same mechanism they
+already support for external auth commands (`apiKeyHelper` for Claude Code,
+`model_providers.<id>.auth.command` for Codex) — so the token is never written
+into either tool's own config file.
+
+- Claude Code talks to `<gateway>/anthropic`
+- Codex uses `<gateway>/chatgpt_passthrough/backend-api/codex` as its provider
+  base and posts to the resulting `.../responses` compatibility route.
+
+It can also install **isolated Impel desktop experiences**. On macOS, Impel
+Claude and Impel ChatGPT are separate vendored app copies. On Windows, Impel
+Claude launches Anthropic's signed vendor executable with its supported 3P
+profile root, while Impel ChatGPT stages OpenAI's signed Electron payload out
+of the protected Store directory and launches it with tenant-specific Codex and
+browser profiles. Each approach keeps the user's normal app profile and
+signed-in account untouched.
+
+## Install
+
+Requires Node.js 18 or newer. The same command works on macOS, Linux, and
+Windows (PowerShell):
+
+```sh
+npm install --global impel-cli
+```
+
+The installable package is intentionally public so Impel users do not need
+access to the private GitHub repository. It contains only this dependency-free
+CLI—no credentials, service secrets, or customer data. Installing it grants no
+Impel access: every protected operation still requires an Impel PAT and the
+gateway/control plane re-checks the user's live product access, scopes, and
+tenant membership.
+
+Releases are published from the private repository with npm Trusted Publishing:
+the registry accepts a short-lived OIDC credential only from the pinned release
+workflow, so no long-lived npm token is stored in GitHub. npm also verifies the
+published tarball's advertised SHA-512 integrity during installation.
+
+Maintainers can exercise the Windows-specific paths from a Linux Docker engine
+with the real Windows Node binary and Wine's `cmd.exe` compatibility layer:
+
+```sh
+docker build --platform linux/amd64 -f test/docker/windows-wine.Dockerfile -t impel-cli-windows-test .
+docker run --rm --platform linux/amd64 impel-cli-windows-test
+```
+
+The repository CI additionally runs the complete suite on `windows-latest`;
+that native job owns the hostile percent/caret npm-shim case that Wine does not
+faithfully emulate.
+
+## Quickstart
+
+```sh
+impel setup                # token → tenant → platform clients → verify
+impel claude               # launch Claude Code with an isolated Impel profile
+impel codex                # launch Codex with an isolated Impel profile
+impel update               # later: update the CLI, apps, and skills in one command
+```
+
+`impel setup` walks through everything below in one command (create your PAT at
+`https://www.useimpel.com/settings/gateway`, paste it at the secure prompt, and
+the wizard does the rest). On Windows it installs either missing official vendor
+CLI from npm, prepares both tenant-isolated CLI profiles, installs the signed
+Claude and ChatGPT desktop apps with separate tenant profiles, and syncs skills.
+On macOS it installs the isolated desktop apps. The individual commands remain
+for piecemeal use:
+
+```sh
+impel auth                 # paste your PAT when prompted
+impel tenant list          # see every organization available to this user
+impel tenant use impel     # select the tenant for accounts, specialists, and history
+impel claude               # launch Claude Code with an isolated Impel profile
+impel codex                # launch Codex with an isolated Impel profile
+impel status               # isolated-launcher readiness, native mode, and reachability
+impel doctor               # make one synthetic request to each provider and measure routing/latency
+
+impel app install          # install both isolated desktop app profiles
+impel app update           # update vendor apps, configs, and supported models
+impel app open claude      # open Claude Desktop with its isolated Impel profile
+impel app open codex       # open ChatGPT/Codex Desktop with its isolated Impel profile
+
+# The normal `claude` and `codex` commands keep using your personal profiles.
+```
+
+Fresh `impel claude` profiles start on **Claude Opus 4.8 with 1M context** and
+also register **Claude Fable 5** in `/model`. You can choose a different
+persistent default there, or override one session with `--model`.
+
+## Commands
+
+```
+impel setup [--pat <pat>] [--tenant <org>] [--skip-apps] [--skip-clis]
+                                             Guided setup: token, tenant, platform clients, verify
+                                             (closes running Claude/ChatGPT apps, updates the vendor
+                                              apps, then installs the vendored Impel apps on macOS;
+                                              installs missing vendor CLIs on Windows)
+impel update [--check] [--skip-apps]         Update EVERYTHING: reinstall the CLI from npm, then
+                                             cascade to `app update all` and `skills sync all`
+impel auth [--pat <pat>] [--gateway <url>] [--app <url>]
+                                             Store your Impel PAT + URLs
+impel token [--tenant <org>]                 Print a selected-tenant bearer
+impel mcp                                    Run the local MCP bridge used by Claude/Codex
+impel claude [claude args...]                Launch isolated Impel Claude Code
+impel codex [codex args...]                  Launch isolated Impel Codex
+
+impel tasks list [--org <org>]               List tickets
+impel tasks get <id>                         Read one ticket
+impel tasks create --title <title> [...]     Create a ticket
+impel tasks update <id> [...]                Update a ticket
+impel tasks delete <id> --yes                Delete a ticket
+
+impel tenant list                            List available organizations
+impel tenant current                         Print the selected organization
+impel tenant use <org> [--launch <target>]   Select a tenant; optionally launch claude, codex, or apps
+impel doctor [--tenant <org>|--all-tenants]  Run synthetic provider, routing, and latency checks
+
+impel use gateway [claude|codex|all]         Switch to the Impel gateway  (default: all)
+impel on [claude|codex|all]                  Alias for `impel use gateway`
+impel use account [claude|codex|all]         Revert to your own login    (default: all)
+impel off [claude|codex|all]                 Alias for `impel use account`
+
+impel skills sync [claude|codex|all]         Sync Bifrost shared skills into managed clients (default: all)
+
+impel status                                 Launcher readiness + native mode + gateway reachability
+impel app install [claude|chatgpt|codex|all] Install isolated apps
+impel app update [claude|chatgpt|codex|all]  Refresh apps, configs, and models
+impel app refresh [claude|chatgpt|codex|all] Configs/catalog/skills only; safe while apps run
+                                             (--stale-only: no-op unless 6h+ since last sync)
+impel app status [claude|chatgpt|codex|all]  Show launcher/vendor status
+impel app open [claude|chatgpt|codex|all]    Launch isolated instances (fast path: opens
+                                             immediately when nothing changed since last open;
+                                             a detached stale-only refresh keeps things current)
+impel app uninstall [target] [--keep-data]   Remove Impel-managed app files
+impel help                                   Show help
+impel --version                              Show version
+
+# `impel setup` no longer takes a per-tool target and never flips native
+# configs; flip a native tool explicitly with `impel use gateway [claude|codex]`.
+```
+
+### `impel auth [--pat <pat>] [--gateway <url>] [--app <url>]`
+
+Stores your PAT, gateway base URL, and app/control-plane URL in `~/.config/impel/config.json`
+(created with mode `0600`, directory `0700`).
+
+- If `--pat` isn't given, you're prompted for it (input is masked).
+- If `--gateway` isn't given, it falls back to (in order): the gateway URL you
+  already had stored, the `IMPEL_GATEWAY_URL` environment variable, then the
+  built-in default **`https://gateway.useimpel.com`**.
+- If `--app` isn't given, it falls back to (in order): the app URL you already
+  had stored, the `IMPEL_APP_URL` environment variable, then the built-in
+  default **`https://www.useimpel.com`**.
+- Trailing slashes on the gateway URL are stripped automatically.
+
+```sh
+impel auth --pat impel_pat_xxxxxxxxxxxx --gateway https://gateway.useimpel.com --app https://www.useimpel.com
+```
+
+### `impel update`
+
+One command brings everything current, in dependency order: the CLI itself
+(`npm install -g impel-cli@latest` from npm, with no GitHub credentials),
+then — re-executing the freshly installed build — `impel app update all`
+(close running apps, update the vendor apps, rebuild the vendored Impel apps)
+and `impel skills sync all` across every managed profile.
+
+Update discovery compares the installed package version with npm's public
+`latest` metadata, cached for 6 hours in
+`~/.config/impel/update-check.json`. It does not invoke Git or contact GitHub.
+
+You'll also hear about updates without asking: `impel claude`, `impel codex`,
+`impel status`, and `impel app open` print a one-line notice when the cached
+remote is ahead, and refresh the cache in a detached background process when
+it's stale (TTY-only, never blocks a launch; set `IMPEL_SKIP_UPDATE_CHECK=1`
+to silence). The Impel desktop apps keep themselves current too: their token
+helper kicks off a detached `impel app refresh --stale-only` on use, which
+re-syncs configs, the model catalog, and skills at most every 6 hours — safe
+while the apps are running because it never swaps an app bundle.
+
+### `impel tasks ...`  (aliases `impel task`, `impel tickets`, `impel ticket`)
+
+CRUDs Impel tickets through the app/control-plane API using the stored PAT. New
+PATs need the `tasks` scope and the user must be a **Workspace member**. Gateway
+members intentionally cannot access tasks or other workspace features, even if
+an older PAT still contains the scope.
+
+```sh
+impel tasks list --scope visible
+impel tasks get IMP-123
+impel tasks create --title "Fix flaky login test" --priority high --labels bug,engineering
+impel tasks update IMP-123 --progress review --assignee rahulvbrahmal@gmail.com
+impel tasks update IMP-123 --description-file brief.md --description-mode replace
+impel tasks delete IMP-123 --yes
+```
+
+Common options: `--org <org>` targets a specific org (default: the PAT's org),
+`--json` prints the raw API response, and `--app <url>` overrides the app URL for
+one command.
+
+### Tenant selection
+
+`impel auth` discovers every organization the PAT owner currently belongs to.
+The default is `impel` when available, otherwise the first organization slug in
+deterministic order. Change it with `impel tenant use <org>`.
+
+The selected tenant controls all gateway-backed surfaces together: subscription
+accounts, usage attribution, model catalog, and specialist discovery. The
+gateway re-verifies both the underlying PAT and current organization membership;
+editing the local config cannot grant access to another tenant.
+
+Isolated CLI state is kept separately under
+`~/.config/impel/cli/tenants/<org>/`, so Claude/Codex history and MCP state do
+not bleed between tenants. `impel tenant use <org> --launch claude|codex|apps`
+selects and launches in one command.
+
+On macOS, desktop app state is isolated under
+`~/.config/impel/apps/tenants/<org>/`. The app bundle in `~/Applications` is a
+launcher for the currently opened tenant; `impel app open` refreshes that
+launcher, the tenant-scoped bearer, model catalog, and specialist MCP arguments
+before starting a new isolated instance. Windows Claude Desktop keeps each
+tenant under `%LOCALAPPDATA%\Claude-3p\Impel\<org>` and launches the unchanged
+signed vendor executable with that profile selected. Windows ChatGPT keeps its
+Codex and browser state under the same tenant-scoped Impel apps root used on
+macOS and launches a staged copy of the unchanged signed Store payload.
+
+### Product access
+
+Impel has two product access levels, independent of organization membership and
+provider-pool administration:
+
+- **Workspace member** — the complete Impel workspace plus the gateway,
+  tenant-scoped inference, and specialist agents.
+- **Gateway member** — the gateway setup/configuration surface, tenant selector,
+  inference, and specialist agents only. Tasks, workspace rooms, notifications,
+  and other collaboration features are unavailable.
+
+The control plane resolves this entitlement live. The CLI caches it only for
+display; the control plane and gateway enforce it again on every protected
+operation. Changing the selected tenant never changes the user's product access.
+Provider launches and `impel doctor` also preflight the PAT's live
+`claude-code-gateway` / `codex-gateway` scopes, so an older single-provider PAT
+gets a direct rotation instruction instead of a misleading model-capacity error.
+
+### `impel doctor`
+
+Runs a real streaming request through each selected provider, so it consumes a
+small amount of provider capacity. Each request contains only a generated
+synthetic marker and asks the model to acknowledge that marker exactly. The
+report verifies:
+
+- live PAT, entitlement, and tenant membership resolution,
+- the tenant-scoped model catalog,
+- a selected subscription account on the response,
+- the gateway-owned request ID and echoed client correlation ID,
+- HTTP, bounded SSE parsing, provider response ID, and successful terminal event,
+- exact request/response acknowledgement, and
+- headers, first-byte, time-to-first-token (TTFT), and total latency.
+
+It never prints the PAT or any real prompt content. The default TTFT warning
+budgets are 6 seconds for Claude and 5 seconds for Codex. A budget miss is shown
+as a warning; add `--strict-latency` to make it fail the command. Connectivity,
+routing, account selection, or acknowledgement errors always produce a non-zero
+exit code.
+
+Organizations may intentionally have only one provider pool. When the live
+catalog reports an exact `no_seat` state for a requested provider, the doctor
+reports that provider as skipped instead of manufacturing a failed request. The
+tenant can pass when another requested provider completes successfully. Expired
+credentials, exhausted capacity, rate limits, ambiguous catalog responses, and
+tenants with no usable requested provider still fail closed.
+
+Use `--gateway <origin>` for a one-run data-plane override. Doctor resolves the
+gateway in this order: `--gateway`, `IMPEL_GATEWAY_URL`, the saved gateway, then
+the canonical default. The override must be a bare HTTP or HTTPS origin and is
+never written back to the stored authentication config.
+
+```sh
+impel doctor
+impel doctor --attempts 2 --strict-latency
+impel doctor --all-tenants --attempts 2 --json > readiness.json
+impel doctor --tenant creador --providers claude
+impel doctor --gateway https://gateway.useimpel.com
+```
+
+`--attempts` is capped at five per provider and a single invocation is capped at
+50 total probes to prevent an accidental high-volume run. JSON output is one
+sanitized report suitable for CI or a rollout checklist.
+
+### `impel token`
+
+Prints **only** a bearer derived from the stored PAT and selected tenant to
+stdout, nothing else. Non-zero exit and a
+stderr message if you haven't run `impel auth` yet.
+
+This is the contract both Claude Code's `apiKeyHelper` and Codex's
+command-backed provider auth expect: a command that is invoked on demand and
+whose stdout is the bearer token. Managed Codex auth and MCP entries call the
+current Node executable plus Impel entry point directly, avoiding npm `.cmd`
+resolution on Windows. Rotating your PAT is still one command
+(`impel auth --pat ...`) and every tool picks it up on its next call/refresh.
+
+### Specialist delegation over MCP
+
+Gateway mode also installs an `impel` stdio MCP server in Claude Code and
+Codex, including the isolated Impel ChatGPT profile. The server runs the Impel
+MCP entry point, reads the PAT from the owner-only Impel
+config, and proxies JSON-RPC to `<gateway>/mcp`; the PAT is never written into
+either client's MCP configuration. Available specialists are discovered at
+runtime, so publishing a new opted-in specialist does not require another CLI
+release.
+
+### Isolated CLI launchers
+
+`impel claude [args...]` and `impel codex [args...]` launch the installed vendor
+CLIs with every argument, the current working directory, stdin/stdout/stderr,
+and the vendor exit code passed through unchanged. They require `impel auth`
+and load gateway authentication plus the Impel MCP server from private,
+Impel-only profiles:
+
+- Claude: `~/.config/impel/cli/tenants/<org>/claude` via `CLAUDE_CONFIG_DIR`
+- Codex: `~/.config/impel/cli/tenants/<org>/codex` via `CODEX_HOME`
+
+The normal `claude` and `codex` commands still use `~/.claude`, `~/.claude.json`,
+and `~/.codex`. The launchers do not read, copy, modify, or remove those native
+profiles, their credentials, or their conversation history. Project-level
+files and the working directory remain available exactly as they are in the
+normal CLIs.
+
+The isolated launchers also add an Impel-only instruction that checks the live
+tenant specialist catalog before non-trivial work. When one available
+specialist clearly matches, the client starts one idempotent specialist run,
+waits for it to finish, and uses its result instead of repeating the task. It
+continues normally when no specialist matches or delegation is unavailable.
+Claude receives this through `--append-system-prompt`; Codex receives it through
+the invocation-local `developer_instructions` override. Neither instruction is
+written to or loaded by the native `claude` or `codex` commands.
+
+The isolated Codex launcher uses Codex's embedded code-mode runtime so MCP tools
+keep working when a vendor install does not include the optional standalone
+`codex-code-mode-host` companion. Only the four specialist-control tools are
+pre-approved for non-interactive delegation; other MCP tools retain Codex's
+normal approval behavior. Its Codex-only instruction also resolves exact Impel
+specialist tools through `tool_search` when the client defers MCP tools instead
+of showing them directly. These settings apply only to `impel codex`.
+
+The isolated Codex profile disables Codex shell snapshots and explicitly keeps
+the default `KEY`/`SECRET`/`TOKEN` environment filter enabled. Before every
+launch, `impel` removes derived `shell_snapshots`, drops inherited direct-auth
+variables such as `CODEX_ACCESS_TOKEN`, and enforces owner-only permissions on
+the managed profile and credential/config files. It also sweeps inactive tenant
+and pre-tenancy Impel CLI profiles, so switching organizations cannot strand an
+older snapshot. These safeguards apply only to Impel-owned `CODEX_HOME`
+directories; native `~/.codex` remains untouched.
+
+On Windows, `impel setup` ensures the official `@anthropic-ai/claude-code` and
+`@openai/codex` packages are available, installing only the missing package(s)
+with the same npm installation that supplies Impel. Use `--skip-clis` to prepare
+the profiles without installing missing vendor CLIs. The launchers and skill
+sync resolve native executables through `PATH`/`PATHEXT`, including global npm
+`.cmd` and `.bat` shims. Windows environment references such as `%NVM_SYMLINK%`
+are expanded during lookup, and the standard npm-global, Claude native-installer,
+and Codex standalone-installer directories are checked even when the parent
+PowerShell PATH is stale. Arguments are forwarded through an explicitly escaped
+`cmd.exe` invocation without Node shell mode; NULs and line breaks, which cannot
+be represented safely through a batch shim, are rejected before anything is
+launched. Managed Codex auth and MCP subprocesses bypass batch shims entirely by
+calling Node directly.
+
+If npm itself fails during setup, the wizard prints the native spawn error and
+the exact vendor-package command to retry in PowerShell. If npm succeeds but the
+new commands remain undiscoverable, close and reopen PowerShell; then use
+`npm prefix --global` to identify the directory that must be on the user PATH.
+Setup exits non-zero and says it is incomplete until both launchers are ready—it
+does not print a success banner after a failed installation.
+
+Windows receives the complete CLI workflow: setup/auth, tenant selection,
+isolated Claude and Codex launches, native profile switching, tasks, skills,
+status, doctor, self-update, and both isolated desktop apps. `impel app install
+claude` installs/updates Anthropic's signed per-user app through winget, writes
+the selected tenant's 3P gateway configuration beneath Anthropic's reserved
+`%LOCALAPPDATA%\Claude-3p\Impel\<tenant>` root, and leaves the executable and
+normal Claude profile unchanged. `impel app install codex` installs/updates
+OpenAI's `OpenAI.Codex` Store package, stages its unchanged signed app payload
+inside Impel's shared app cache, and writes separate Codex and Chromium
+profiles. `impel app open claude` and `impel app open codex` launch those
+isolated profiles without changing either normal vendor profile.
+
+For Claude, the Impel PAT is supplied only to the launched child process as an
+authentication token and disappears when that process exits; it is never
+written into the isolated Claude profile. The launcher also recognizes
+Claude's standard native-installer location at `~/.local/bin/claude` when that
+directory is not present in the parent process's `PATH`.
+
+```sh
+impel claude
+impel claude -p "summarize this repository" --output-format json
+impel codex
+impel codex exec --json "review the current diff"
+```
+
+`impel use gateway` remains available for users who intentionally want to
+switch their native profiles in place; the isolated launchers are the safer
+default when personal and Impel sessions should coexist.
+
+### `impel use gateway [claude|codex|all]`  (alias `impel on`)
+
+Turns **on** gateway mode for the given tool (default `all`). Requires `impel auth`
+first.
+
+**Claude Code** — merges into `~/.claude/settings.json` (creating it if needed,
+leaving every other key — permissions, hooks, other env vars — untouched):
+
+```json
+{
+  "apiKeyHelper": "impel token",
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://gateway.useimpel.com/anthropic"
+  }
+}
+```
+
+**Codex** — merges into `~/.codex/config.toml`. Codex supports pointing
+`model_provider` at a custom `[model_providers.<id>]` table, plus a
+**command-backed** bearer token via a `[model_providers.<id>.auth]` sub-table
+(`command` + `args`, re-invoked on a timer and on auth retries — the same shape
+as Claude Code's `apiKeyHelper`), so we reuse `impel token` there too instead of
+writing the PAT into `config.toml` or `~/.codex/auth.json`. The block written
+(fenced by markers, so everything else in your `config.toml` — other
+`model_providers`, `mcp_servers`, sandbox policy — is left alone):
+
+```toml
+model_provider = "impel"
+
+# >>> impel-cli managed block (model_providers.impel) >>>
+# Generated by `impel use gateway codex`. Safe to re-run; do not hand-edit
+# the lines between the markers above/below, they'll be overwritten.
+[model_providers.impel]
+name = "Impel Gateway"
+base_url = "https://gateway.useimpel.com/chatgpt_passthrough/backend-api/codex"
+wire_api = "responses"
+
+[model_providers.impel.auth]
+command = "impel"
+args = ["token"]
+timeout_ms = 5000
+refresh_interval_ms = 300000
+# <<< impel-cli managed block <<<
+```
+
+Before overwriting anything, `impel` **backs up** what was there (any prior
+`apiKeyHelper` / `ANTHROPIC_BASE_URL`, and the prior Codex `model_provider`
+value) into `~/.config/impel/config.json`, so `impel use account` can restore it
+exactly. If `config.toml` already has a `[model_providers.impel]` table that
+wasn't written by this tool, `impel` refuses to touch the file and tells you to
+resolve it manually rather than risk emitting invalid/duplicate TOML.
+
+### `impel use account [claude|codex|all]`  (alias `impel off`)
+
+Turns gateway mode **off** and restores your normal account-based setup. It
+removes **only** the Impel-added bits, never your own config:
+
+- **Claude Code** — removes `apiKeyHelper` only if it's `"impel token"`, and
+  `env.ANTHROPIC_BASE_URL` only if it equals `<gateway>/anthropic`. Then restores
+  whatever those keys held before gateway mode (from the backup). If there was
+  nothing before, they're deleted (and an emptied `env` is dropped).
+- **Codex** — removes the marker-fenced `[model_providers.impel]` block, and
+  resets `model_provider` **only if it currently reads `"impel"`** — back to its
+  backed-up prior value, or, if there was none, removes the line entirely so
+  Codex falls back to its built-in default. All other tables are untouched.
+
+`impel use account` doesn't require the PAT and is safe to run repeatedly (if a
+tool is already in account mode it just says so and changes nothing).
+
+### `impel skills sync [claude|codex|all]`
+
+Syncs Impel's **Bifrost shared skills** into your managed Claude Code and Codex
+clients. The gateway publishes a public, per-client plugin marketplace whose
+bundled plugin — `bifrost-all-skills` — contains every served skill:
+
+- Claude Code registers its manifest URL:
+  `<gateway>/api/skills/serve/claude-code/.claude-plugin/marketplace.json`
+- Codex registers the Git source `<gateway>/api/skills/serve/codex`; its
+  marketplace manifest lives at `<source>/.agents/plugins/marketplace.json`.
+
+The sync is idempotent: it registers the marketplace, ensures `bifrost-all-skills`
+is installed, then runs the client's refresh commands so an already-installed
+plugin picks up a newer bundle. It reads each marketplace's registered `name`
+from the served `marketplace.json` to pin installs and refreshes. Codex receives
+the Git source rather than the nested manifest URL because its CLI clones the
+source before discovering `.agents/plugins/marketplace.json`.
+
+You rarely need to run it by hand — it runs **automatically** at the end of every
+install/update path:
+
+- `impel use gateway ...` / `impel setup ...` (native `~/.claude` / `~/.codex`)
+- `impel app install` / `impel app update` (each isolated desktop app profile)
+
+`impel skills sync` also covers the isolated `impel claude` / `impel codex` CLI
+profiles and installed desktop apps when they exist. Skill syncing is
+best-effort: if a client CLI, its `plugin` subcommand, or the gateway is
+unavailable, it logs a warning and moves on — it never fails the parent command.
+Set `IMPEL_SKIP_SKILL_SYNC=1` to disable it entirely (offline/CI).
+
+### `impel status`
+
+Shows whether the isolated CLI launchers are ready, and whether each native
+tool profile is currently in **GATEWAY** or **ACCOUNT** mode (detected from
+whether the Impel markers / base URL are present), plus:
+
+- the configured gateway URL,
+- whether a PAT is stored (masked, e.g. `impel_pat_ab12...wxyz`),
+- the live Workspace member / Gateway member entitlement when available,
+- a best-effort reachability check: a `POST` to `<gateway>/anthropic/v1/messages`
+  with a 5s timeout. Any HTTP response (including a 4xx) counts as "reachable" —
+  this checks the network path and gateway routing, not the request itself. A
+  `401`/`403` is called out separately since it usually just means the stored PAT
+  was rejected, not that the gateway is down.
+
+Codex CLI and the Codex IDE extension / desktop app share the same
+`~/.codex/config.toml`, so they always report the same mode.
+
+## Isolated Impel desktop apps
+
+### Windows Claude and ChatGPT Desktop
+
+```powershell
+impel app install claude
+impel app open claude
+impel app status claude
+impel app install codex
+impel app open codex
+impel app status codex
+```
+
+The Windows path does not clone, patch, or re-sign Claude. It locates either
+Anthropic's standard Squirrel installation or its signed MSIX package, then
+launches the vendor executable with the supported `CLAUDE_USER_DATA_DIR`
+override. Anthropic's MSIX manifest explicitly reserves `%LOCALAPPDATA%\Claude-3p`
+for unvirtualized third-party profiles, so each Impel tenant lives below that
+root. The app's normal first-party profile is not read or changed. `impel setup`
+installs this profile by default; use `--skip-apps` to omit it.
+
+For ChatGPT/Codex Desktop, Windows installs the official Microsoft Store product
+`9PLM9XGG6VKS` (`OpenAI.Codex`). Windows blocks other programs from directly
+executing Electron inside `C:\Program Files\WindowsApps`, so Impel copies the
+vendor's complete `app` payload, unchanged, into a shared managed cache. It
+then launches that copy with a separate `CODEX_HOME` and
+`CODEX_ELECTRON_USER_DATA_PATH` (plus Electron `--user-data-dir` as a legacy
+fallback). The normal Store app, `%USERPROFILE%\.codex`, and the normal ChatGPT
+browser profile are not read or changed. `chatgpt` and `codex` are equivalent
+app-target names.
+
+### macOS Claude and ChatGPT
+
+`impel app install` creates `Impel Claude.app` and `Impel ChatGPT.app` in
+`~/Applications`. They have separate bundle identities and gateway
+configuration:
+
+- Impel Claude is an APFS-cloned vendored copy of the official app with its own
+  bundle and helper identities. Its LaunchServices environment sets the
+  vendor-supported `CLAUDE_USER_DATA_DIR` and writes the 3P gateway `configLibrary` below
+  `~/.config/impel/apps/claude`. A narrowly version-checked compatibility patch
+  connects Claude's native plan-usage meter to the authenticated aggregate
+  Claude subscription pool exposed by the Impel gateway.
+- Impel ChatGPT is an APFS-cloned vendored copy of the official app. Its wrapper
+  sets `CODEX_HOME`, passes a separate Chromium `--user-data-dir`, and writes its
+  provider config and model catalog below `~/.config/impel/apps/chatgpt`. It also
+  supplies a process-scoped, Codex-compatible wrapper around the Impel PAT so
+  native `/status` requests can read the organization's aggregated subscription
+  pool from the gateway. Its generated Codex config uses the same snapshot and
+  subprocess-environment hardening as `impel codex`; install, update, and every
+  direct app launch also remove older snapshots for the selected profile, while
+  app install/update/open sweeps inactive tenant and legacy Impel app profiles.
+- Neither app changes `~/.claude`, `~/.claude.json`, `~/.codex`, or the
+  normal vendor app's browser/profile data.
+
+The official Claude and ChatGPT apps remain separate installations and keep
+their normal accounts, updater, profiles, and bundle identities. The installer
+uses an existing official app when found. If one is missing and
+Homebrew is available, it installs the corresponding cask into
+`~/Applications`. `impel app update` upgrades Homebrew-managed vendor apps,
+rebuilds the isolated apps, reapplies version-checked compatibility patches,
+rewrites versioned configs, and fetches the PAT-scoped model catalog from
+`<gateway>/v1/models`. If a vendor update changes a required renderer contract,
+the update fails without replacing the working Impel copy. If the model endpoint
+is temporarily unavailable, the installer retains functionality using the CLI's
+bundled catalog.
+
+For ChatGPT/Codex, the gateway controls which models and capabilities are
+enabled while the installer merges those entries with the vendor app's native
+catalog. The Impel copy relaxes the vendor renderer's ChatGPT-account-only Fast
+gate because gateway auth supplies the entitlement instead. The copy is then
+ad-hoc signed locally. This preserves model-specific instructions and exposes
+the same reasoning-effort and service-tier controls as the normal app, including
+Ultra where supported and Fast only on models that advertise the `priority`
+tier. Inference uses an explicit non-WebSocket Impel model provider so Codex
+cannot fall back to the vendor's hard-coded `chatgpt.com` transport with an
+Impel PAT. Config refreshes replace only the Impel-managed gateway block; plugins,
+desktop preferences, projects, and other settings written by the isolated app
+are kept.
+
+Both vendored copies are ad-hoc signed locally after their bundle identities and
+launch wrappers are installed. The Claude 3P config necessarily contains the PAT because that app accepts a
+gateway API key rather than a token-helper command. It is stored in the same
+owner-only Impel config tree as the primary credential. ChatGPT/Codex uses a
+command-backed helper and does not copy the PAT into TOML. The installable app
+also reads that helper into its own process environment for Codex account-status
+compatibility; the value disappears when the app exits.
+
+## Switching back and forth
+
+The whole point: flipping between the gateway and your own account is one
+command, per tool, and always reversible.
+
+```sh
+impel on                 # both tools -> gateway
+impel off                # both tools -> your own account (restores prior config exactly)
+
+impel on codex           # just Codex -> gateway, leave Claude Code alone
+impel off claude         # just Claude Code -> account
+
+impel status             # see where each tool stands right now
+```
+
+How the clean revert is guaranteed: `impel on` records the pre-existing values
+(your own `apiKeyHelper` / `ANTHROPIC_BASE_URL`, and Codex's prior
+`model_provider`) into `~/.config/impel/config.json` **before** overwriting them,
+and only ever captures a real *account-mode* value (re-running `impel on` never
+clobbers the backup with Impel's own values). `impel off` removes only keys that
+still point at Impel and restores those backups — so a full `on` → `off`
+round-trip leaves `settings.json` and `config.toml` byte-for-byte back to where
+they started, with all your unrelated keys and tables intact.
+
+If you'd rather revert by hand: delete `apiKeyHelper` + the Impel
+`ANTHROPIC_BASE_URL` from `~/.claude/settings.json`; delete the block between the
+`# >>> impel-cli managed block ... >>>` / `# <<< impel-cli managed block <<<`
+markers in `~/.codex/config.toml` and reset `model_provider`; and
+`rm -rf ~/.config/impel` to forget the PAT + gateway entirely.
+
+## Codex compatibility route
+
+The installable app uses an explicit Codex model provider at
+`<gateway>/chatgpt_passthrough/backend-api/codex`, producing the request path
+`/chatgpt_passthrough/backend-api/codex/responses`. The provider disables
+WebSockets because the vendor's built-in ChatGPT provider derives that URL from
+`chatgpt.com` rather than the configured account-service base. The gateway
+preserves the request body while replacing the Impel PAT with the selected
+ChatGPT subscription credential.
+
+The installable Impel ChatGPT app also points Codex's account client at
+`<gateway>/chatgpt_passthrough/backend-api`. The gateway exposes a virtual Impel
+pool identity and `GET .../wham/usage`, aggregating each primary and secondary
+subscription window across all active Codex seats with equal-seat weighting.
+This lets the native `/status` surface show pool capacity without exposing any
+provider account identity or OAuth credential.
+
+Before every launch, the wrapper refreshes Codex's supported personal-access-token
+login record from the tenant helper. That keeps the desktop app in native
+ChatGPT-account mode, allowing `/status` to request the aggregate five-hour and
+weekly windows instead of treating Impel as an API-key-only provider.
+
+The gateway also exposes `POST /v1/responses`, but that is the conventional
+OpenAI Responses front door for SDK/Eve traffic and may normalize the body
+(including enforcing `store: false`). The CLI deliberately does not use it.
+
+## Design notes
+
+- **Zero dependencies.** Arg parsing, JSON/TOML merging, masked prompts, and the
+  reachability check are all hand-rolled against Node stdlib (`fs`, `os`,
+  `path`, `readline`, global `fetch`). No `chalk`, no `commander`, no `inquirer`.
+- **The PAT lives in exactly one place:** `~/.config/impel/config.json` (mode
+  `0600`). Both Claude Code and Codex fetch it on demand by shelling out to
+  `impel token` rather than copying it into their own config files — one token,
+  one rotation path, no stale copies.
+- **The `config.toml` merge is intentionally narrow**, not a general TOML
+  parser: it only ever touches a single top-level `model_provider` line and its
+  own fenced `[model_providers.impel*]` block, leaving unrelated tables (other
+  providers, MCP servers, sandbox policy, etc.) untouched.
+
+## Sources consulted for the Codex config
+
+- https://developers.openai.com/codex/config-reference
+- https://developers.openai.com/codex/config-advanced
+- https://developers.openai.com/codex/auth
+- https://developers.openai.com/codex/ide