Skip to content

SKILL.md

Latest commit

 

History

History
53 lines (39 loc) · 2.8 KB

SKILL.md

File metadata and controls

53 lines (39 loc) · 2.8 KB
Raw
name codex-account-switcher
description Maintain and publish the macOS Codex Account Switcher app. Use when Graham asks to tweak, build, package, sanitize, or publish the menu-bar account switcher.

Codex Account Switcher Skill

Use this skill for the local/public Codex Account Switcher project.

Project Location

Work from the root of this repository.

Important Public-Safety Rules

  • Never commit ~/.codex/auth.json, ~/.codex/accounts/, registry.json, tokens, account IDs, real account emails, or usage snapshots.
  • Never commit build/ or module caches.
  • Public account initials must be generic: use the first alphanumeric character from each account email unless the app user sets a custom label.
  • Switch commands should use email queries, not numeric selectors like 01 or 02.

Build

./build.sh

Install Locally

./install.sh

Behavior Summary

  • Current local update is v1.8.3.1 / build 1831.
  • Menu bar supports detailed and compact 5-hour or weekly usage displays.
  • Active account is bright; inactive accounts are dimmed.
  • Dropdown shows 5-hour usage for all accounts.
  • The main panel supports three/four saved accounts with a compact 2x2 card grid and an empty slot.
  • Reset-credit reads use a five-minute cache independent from the fast active-usage refresh, and account reset checks run concurrently with a cap of three.
  • Reset redemption is not automatically retried and is only reported as confirmed after both the credit count and live usage windows agree.
  • External helper commands have timeouts, Computer Use discovery is version-independent, and only the ten newest auth backups per account are retained.
  • Verification is ./run-tests.sh, ./build.sh, ./install.sh, then ./verify-install.sh.
  • Live usage values that come back as 400/401 should be treated as expired login, not healthy unknown usage. Ask Graham to remove/re-add or re-login that labelled account.
  • The relaunch path may see leftover Codex helper PIDs; if Codex can still open, do not treat helper survivors alone as a failed relaunch.
  • Low-usage auto-switch is notification/action based: the user clicks Switch Now.
  • Launch-at-login is handled via a user LaunchAgent.

Troubleshooting Notes

  • If the menu-bar title gets stuck on Adding account after a manual login, quit CodexAccountSwitcher and reopen /Applications/Codex Account Switcher.app, then run codex-auth list to confirm the registry.
  • If the device-code button crashes or fails, inspect the Terminal/AppleScript helper path first. Do not assume the account registry is broken if codex-auth list already shows the re-added account with live usage.
  • After every local tweak, run ./build.sh, ./install.sh, quit CodexAccountSwitcher, reopen /Applications/Codex Account Switcher.app, and verify the running process path.