| name | codexm-usage |
| description | Use when a user wants help managing multiple Codex login snapshots with codexm, including saving, listing, switching, launching, watching quota signals, or understanding managed Desktop behavior. |
codexm Usage
Use this skill when the user is asking how to use codexm as a tool, including account dashboard flows, share-bundle import/export, and codexm run. Do not use it for codex-team implementation, testing, release, or code review work.
How to use
- First identify the user's goal: inspect state, inspect current usage, compare accounts, add a new login, save or refresh the current login, switch accounts, open the account dashboard, export or import a share bundle, launch Desktop, run the CLI through the restart wrapper, enable or inspect the local proxy account, watch quota behavior, set up shell completion, or explain command behavior.
- Prefer the shortest command that matches that goal.
- If the user is unsure about current state, start with
codexm current or codexm list; use codexm doctor when they are debugging runtime or Desktop consistency.
- If the question is about Desktop behavior, explain the difference between
switch, launch, autoswitch, and watch before giving commands.
Route by task
Response Guidance
- When the user expects Desktop to switch accounts immediately, explain the difference between
switch and launch.
- If the user mentions an in-progress managed Desktop thread, mention the default wait behavior and the
--force trade-off.
- If the user asks for background auto-switching on managed Desktop or proxy flows, route them to
codexm autoswitch enable; use codexm watch when they explicitly want the foreground quota monitor, and add --no-auto-switch only when they want observation without account changes.
- If the user asks for current usage, prefer
codexm current; add --refresh only when they explicitly want the latest data.
- If the user is debugging mismatches between local auth, managed Desktop, and direct runtime reads, route them to
codexm doctor.
- If the user wants to add another account without changing current auth, prefer
codexm add <name>; use --device-auth for remote/headless machines and --with-api-key only when they explicitly want API-key auth.
- If a saved account already exists but its auth or refresh token is broken, route them to
codexm replace <name> so the snapshot is overwritten in place.
- If the user wants to update the saved snapshot for the account already active in local auth, route them to
codexm update.
- If the user asks how to compare accounts or understand why
switch --auto picked one, prefer codexm list --verbose.
- If the user wants an interactive picker, filtering, import/export, delete, or Desktop launch in one place, route them to plain
codexm in a TTY or codexm tui [query].
- If the user wants to move a login to another trusted machine without re-login, route them to
codexm export, codexm inspect, and codexm import, and mention that share bundles are plain auth snapshots for fully trusted recipients only.
- If the user wants a CLI workflow that survives account-triggered restarts, route them to
codexm run -- ...codexArgs.
- If the user wants Codex or another OpenAI-compatible tool to use one stable local endpoint while
codexm routes to saved upstream accounts internally, route them to codexm proxy enable, codexm proxy status, and later codexm proxy disable; mention that codexm switch <name> updates only the proxy's current upstream while proxy remains enabled and does not replace the synthetic proxy auth, autoswitch only moves that upstream after quota-exhaustion signals, proxy websocket turns and buffered REST requests can auto-replay once on quota exhaustion before user-visible or side-effectful output starts, both the dashboard and codexm list always show the aggregate proxy pool row even before proxy mode is enabled, the pool quota/ETA count non-protected eligible accounts with quota snapshots including exhausted ones, managed Desktop usage/account reads stay on the synthetic proxy account surface, @ marks the configured current upstream while proxy stays enabled, and Proxy last upstream: ... / Last upstream: ... still describe the most recent real proxy hit when known.
- If a fresh quota read fails, explain that
codexm list and the dashboard can fall back to that account's last good quota snapshot for up to 7 days and will mark the row as [stale].
- If the user wants proxy behavior for one isolated run without writing sessions/auth/config into the live runtime, route them to
codexm run --proxy -- ...codexArgs; explain that codexm-managed proxy entrypoints rewrite the transport URLs for both live Desktop/CLI flows and isolated proxy runs, so live Responses websocket turns as well as REST /v1 traffic honor the local proxy, while unmanaged bare codex / Desktop launches are still outside that guarantee.
- If the user says the default proxy port is occupied, mention
CODEXM_PROXY_PORT=<port> for a shared-daemon-wide override, and mention that codexm proxy enable --port <port> overrides the env var for that command.
- If the user asks for shell completion, route them to
codexm completion <zsh|bash> and mention that the generated scripts complete commands, known subcommands, flags after - / --, and saved account names dynamically.
- When the user wants machine-readable output, include
--json where supported.
- If the user wants raw command help only, answer with commands first and keep explanation short.
