Skip to main content
The settings hub provides interactive configuration for dashboard display, behavior, theme, and advanced backend options.

​
Accessing Settings

From the main dashboard:
  1. Navigate to “Settings” in the menu
  2. Press Enter to open the settings hub
The settings hub displays five configuration panels:
  • Account List Display: Configure badges, layout, and sorting
  • Summary Fields: Choose and reorder statusline fields
  • Behavior: Set auto-return timing and fetch options
  • Theme: Select color palette and accent colors
  • Backend: Advanced rotation, quota, and timeout settings

​
Account List Display

Controls how accounts appear in the main dashboard.

​
Available Settings

SettingDefaultDescription
Show Status BadgesOnDisplay [ok], [active], [rate-limited] badges
Show [current] BadgeOnMark the active Codex account with [current]
Show Last UsedOnDisplay relative usage time (“today”, “2d ago”)
Show Limits (5h / 7d)OnDisplay quota bars for rolling windows
Show Limit CooldownsOnShow reset timers next to quota bars
Show Fetch StatusOnDisplay background refresh progress in subtitle
Show Details for UnselectedOffShow details on all rows vs selected row only
Highlight Current RowOnUse stronger color on the current account
Enable Smart SortOnSort accounts by readiness score
Pin [current] when tiedOffKeep current account at top when equally ready
Quick Switch Uses VisibleOnNumber keys (1-9) follow visible order

​
Sort Mode

  • Ready-First: Sorts accounts by health, quota, and availability
  • Manual: Preserves the order accounts were added

​
Layout Mode

  • Compact + Details Pane: One-line rows with details shown for selected account only (default)
  • Expanded Rows: Multi-line rows showing details for all accounts

​
Keyboard Shortcuts

KeyAction
1-9Quick toggle numbered options
MCycle sort mode (Ready-First ↔ Manual)
LCycle layout mode (Compact ↔ Expanded)
SSave changes and return
RReset to defaults
QCancel without saving

​
Live Preview

The settings screen displays a live preview of how accounts will appear: 
Preview
1. [email protected] [current] [active]
Last used: today  |  Limits: 5h ██████▒▒▒▒ 62% | 7d █████▒▒▒▒▒ 49%
details shown on selected row only
The preview updates immediately as you change settings.

​
Summary Fields

Controls which fields appear in the account statusline and their order.

​
Available Fields

FieldDefaultDescription
Last UsedOn (order 1)Relative usage time
Limits (5h / 7d)On (order 2)Quota bars and percentages
Status TextOn (order 3)Status text when badges are hidden

​
Field Ordering

Fields display in the order you configure:
  1. First two fields appear on the primary line
  2. Additional fields appear on a secondary line (if expanded rows enabled)

​
Keyboard Shortcuts

KeyAction
1-3Toggle field on/off
[Move focused field up
]Move focused field down
SSave changes and return
RReset to defaults
QCancel without saving

​
Example Configurations

Minimal display (limits only): 
5h ██████▒▒▒▒ 62% | 7d █████▒▒▒▒▒ 49%
Status-first display (status, last-used, limits): 
Status: active  |  Last used: today  |  Limits: 5h 62% | 7d 49%

​
Behavior Settings

Controls timing, auto-return, and background fetch behavior.

​
Auto-Return Timing

After performing an action (set current, delete, etc.), the dashboard can automatically return:
DelayUse Case
1sFastest loop for frequent actions
2sBalanced default for most users (default)
4sMore time to read action output

​
Additional Options

SettingDefaultDescription
Pause on key pressOnAny key stops auto-return timer
Auto-fetch limits on menu openOnRefresh quota when opening dashboard
Show limit refresh statusOnDisplay [2/7] fetch progress in subtitle
Limit cache TTL5mHow fresh cached quota must be before refresh

​
Cache TTL Options

TTLDescription
1mRefresh quota every minute
5mRefresh quota every 5 minutes (default)
10mRefresh quota every 10 minutes

​
Keyboard Shortcuts

KeyAction
SSave changes and return
RReset to defaults
QCancel without saving

​
Theme Settings

Customize dashboard colors and visual style.

​
Theme Presets

PresetDescription
GreenClassic terminal green (default)
BlueModern blue palette

​
Accent Colors

ColorUse
GreenSuccess states, current account (default)
CyanAccent highlights
BlueCool accent variant
YellowWarning states, attention markers

​
Live Preview

Theme changes preview immediately:
  • Navigate through palette and accent options
  • See colors update in real-time
  • Press Q to cancel and restore original theme
  • Press S to save and apply the new theme

​
Keyboard Shortcuts

KeyAction
SSave changes and apply theme
RReset to defaults
QCancel and restore original theme

​
Backend Settings

Advanced settings for rotation, quota, refresh, and performance.

​
Categories

​
Session & Sync

Controls account synchronization and session behavior.
SettingDefaultDescription
Enable Live SyncOnKeep accounts synced when files change in another window
Enable Session AffinityOnTry to keep each conversation on the same account
Enable Per-Project AccountsOffKeep separate account lists for each project
Enable Session RecoveryOnRestore recoverable sessions after restart
Enable Auto ResumeOnAutomatically continue sessions when possible
Live Sync Debounce100msWait before applying sync file changes
Live Sync Poll5sHow often to check files for updates
Session Affinity TTL1hHow long conversation-to-account mapping is kept
Session Affinity Max Entries256Maximum stored conversation mappings

​
Rotation & Quota

Controls quota tracking and retry behavior.
SettingDefaultDescription
Enable Quota DeferralOnDelay requests before limits are fully exhausted
Retry When All Rate-LimitedOnIf all accounts limited, wait and try again
5h Remaining Threshold5%Start delaying when 5h remaining reaches this percent
7d Remaining Threshold5%Start delaying when weekly remaining reaches this percent
Max Preemptive Deferral5mMaximum time allowed for quota-based delay

​
Refresh & Recovery

Controls token refresh timing and backup behavior.
SettingDefaultDescription
Enable Token Refresh GuardOnRefresh tokens early in the background
Enable Storage BackupsOnCreate backup before account data changes
Refresh Guard Interval30sHow often to scan for tokens near expiry
Refresh Guard Buffer5mHow early to refresh before expiry
Token Refresh Buffer5mRefresh this long before token expiry

​
Performance & Timeouts

Controls speed optimization and timeout limits.
SettingDefaultDescription
Enable Fast Session ModeOffUse lighter request handling for faster responses
Enable Parallel ProbingOnCheck multiple accounts at the same time
Fast Session Max Inputs100Max number of input items kept in fast mode
Parallel Probe Concurrency3Maximum checks running at once
Request Timeout60sMax time to wait for a request
Stream Stall Timeout45sMax wait before stuck stream is retried
Network Error Cooldown5sWait time after network errors before retry
Server Error Cooldown10sWait time after server errors before retry

​
Keyboard Shortcuts

KeyAction
EnterToggle setting or open category
+ / -Adjust numeric setting
SSave all backend changes
RReset all backend settings to defaults
QCancel without saving

​
Category Navigation

  1. Select a category from the backend settings hub
  2. Press Enter to open the category
  3. Navigate settings within the category
  4. Press Q to return to the hub (changes preserved)
  5. Navigate to another category or save all changes with S

​
Settings Persistence

All settings are saved to: 
~/.codex/multi-auth/settings.json
Or, if using a custom root: 
$CODEX_MULTI_AUTH_DIR/settings.json

​
Save Behavior

  • Save (S): Writes changes to disk immediately
  • Cancel (Q): Discards draft changes, no file modification
  • Reset (R): Restores panel defaults, requires S to persist

​
Conflict Resolution

If settings file is modified externally while editing:
  1. Your changes are merged with latest file contents
  2. Your panel-specific changes take precedence
  3. Other panels remain unchanged
  4. Write failures are logged but don’t crash the dashboard

​
Retry Logic

Settings writes use automatic retry on transient failures:
  • EBUSY (file busy): Retries with exponential backoff
  • EPERM (permission denied): Retries up to 4 times
  • EAGAIN (resource temporarily unavailable): Retries with delay
  • 429 (rate limited): Respects Retry-After header
Maximum retry delay: 30 seconds

​
Environment Overrides

Some settings can be overridden with environment variables:
VariableOverridesExample
CODEX_AUTH_FETCH_TIMEOUT_MSRequest Timeoutexport CODEX_AUTH_FETCH_TIMEOUT_MS=90000
CODEX_AUTH_STREAM_STALL_TIMEOUT_MSStream Stall Timeoutexport CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=60000
CODEX_TUI_V2Enable TUI v2export CODEX_TUI_V2=1
CODEX_TUI_COLOR_PROFILEColor profileexport CODEX_TUI_COLOR_PROFILE=truecolor
CODEX_TUI_GLYPHSGlyph styleexport CODEX_TUI_GLYPHS=unicode
Environment variables take precedence over settings file values.

Build docs developers (and LLMs) love

Get started for freeTalk to us