CDX Manager

Run multiple Codex and Claude sessions from one terminal. Switch between accounts instantly.

If you use AI coding tools at scale ; multiple accounts, multiple providers : you know the friction: re-authenticating, losing context, juggling environment variables. cdx removes all of that.

One command to launch any session. Zero auth juggling.

Table of Contents

• What it does
• Technical Overview
• Getting Started
• All Commands
• JSON Output
• Available Scripts
• Windows Support
• Project Structure
• Data Layout
• Troubleshooting
• Contributing
• License

What it does

• Multiple accounts, one tool. Register as many Codex or Claude sessions as you need. Each one gets its own isolated auth environment — no cross-contamination between accounts.
• Instant launch. cdx work opens your "work" session. cdx personal opens another. No config files to edit mid-flow.
• Auth guardrails. cdx checks authentication before launching. If a session is not logged in, it tells you exactly what to run — no silent failures.
• Usage at a glance. cdx status shows token usage, 5-hour window quota, weekly quota, and last-updated timestamps for every session in one aligned table.
• Passive status resolution. If a session has no recorded status, cdx reads it directly from the provider's session logs and JSONL history — no manual sync required.
• Session transcript capture. Every launch is recorded to a local log file via script, giving you a full terminal transcript for each session.
• Clean removal. cdx rmv wipes a session and its entire auth directory. No orphaned files, no stale credentials.

Technical Overview

• Python 3.9+, zero runtime dependencies.
• Environment isolation per session:
  • Codex sessions override CODEX_HOME to a dedicated profile directory.
  • Claude sessions override HOME to a dedicated profile directory.
  • New Codex sessions seed their auth home from your existing global ~/.codex/auth.json when available, so an already logged-in Codex CLI can be reused without giving up per-session isolation afterward.
• Persistence:
  • Session registry at ~/.cdx/sessions.json (versioned JSON store).
  • Per-session state at ~/.cdx/state/<name>.json.
  • Auth and provider data under ~/.cdx/profiles/<name>/.
  • All paths are URL-encoded to support arbitrary session names.
• Status resolution pipeline:
  • Primary source: recorded status fields on the session record.
  • Fallback: status-source scans provider JSONL history files and terminal log transcripts, strips ANSI/OSC sequences, and extracts usage%, 5h remaining%, and week remaining% via pattern matching.
• Claude status refreshes are cached briefly by default; pass --refresh to force a live rate-limit probe.
• If script is unavailable, Codex launch falls back to running without transcript capture.
• On Windows, transcript capture is optional. If no compatible script wrapper is installed, Codex still launches normally without transcript capture.
• Auth probe: synchronous subprocess call to codex login status or claude auth status before any interactive launch.
• Signal forwarding: SIGINT, SIGTERM, and SIGHUP are forwarded to the child process and produce clean exit codes.
• Test stack: Python built-in unittest runner with no test framework dependency.

Getting Started

Prerequisites

• Node.js 18+ with npm
• Python 3.9+
• codex and/or claude CLI installed and available in your PATH

On Windows, the npm launcher looks for Python in this order: py -3, python, then python3. Make sure at least one of those commands resolves to Python 3.

Install

From npm:

npm install -g cdx-manager

With pipx:

pipx install cdx-manager

With uv:

uv tool install cdx-manager

On Windows with PowerShell:

npm install -g cdx-manager

With the standalone PowerShell installer:

Invoke-WebRequest https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.ps1 -OutFile install.ps1
# Optional: set CDX_SHA256 before running if you have a trusted checksum
powershell -ExecutionPolicy Bypass -File .\install.ps1

With the standalone GitHub installer:

curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
# Optional: set CDX_SHA256 before running if you have a trusted checksum
sh install.sh

For a specific version:

curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
CDX_VERSION=v0.4.4 sh install.sh

From source:

git clone <repo>
cd cdx-manager
make install

From source on Windows:

git clone <repo>
cd cdx-manager
npm install -g .

cdx is now available globally. Changes to the source take effect immediately — no reinstall needed.

To update an installed copy later:

cdx update

To uninstall:

make uninstall

To uninstall on Windows after npm install -g:

npm uninstall -g cdx-manager

Alternatively, for a non-symlinked global source install:

npm install -g .

Security note:

• The standalone installers try to resolve official release checksums from checksums/release-archives.json.
• You can still override verification explicitly through CDX_SHA256.
• Prefer npm, pipx, or uv when you want registry-backed install flows.
• If you use the standalone script, download it first, inspect it, and prefer a release with an official checksum entry.

Environment

By default, cdx stores all data under ~/.cdx/. Override with:

export CDX_HOME=/path/to/custom/dir

Optional runtime knobs:

export CDX_CLAUDE_STATUS_MODEL=claude-haiku-4-5-20251001
export CDX_SCRIPT_BIN=script
export CDX_SCRIPT_ARGS='-q -F {transcript}'

PowerShell equivalents:

$env:CDX_HOME = "C:\cdx-data"
$env:CDX_CLAUDE_STATUS_MODEL = "claude-haiku-4-5-20251001"
$env:CDX_SCRIPT_BIN = "script"
$env:CDX_SCRIPT_ARGS = "-q -F {transcript}"

Command Prompt equivalents:

set CDX_HOME=C:\cdx-data
set CDX_CLAUDE_STATUS_MODEL=claude-haiku-4-5-20251001
set CDX_SCRIPT_BIN=script
set CDX_SCRIPT_ARGS=-q -F {transcript}

Quick Start

# Register a Codex session
cdx add work

# Register a Claude session
cdx add claude personal

# List all sessions
cdx

# Launch a session
cdx work

# Check usage across all sessions
cdx status

All Commands

| Command | Description | |---|---| | cdx | List all sessions with last-updated timestamps | | cdx --json | List all sessions as a machine-readable JSON payload | | cdx <name> | Launch a session (checks auth first) | | cdx <name> [--json] | Launch a session; --json returns a structured success payload after the interactive run ends | | cdx add [provider] <name> [--json] | Register a new session (provider: codex or claude, default: codex) | | cdx cp <source> <dest> [--json] | Copy a session into another session name, overwriting the destination if it exists | | cdx ren <source> <dest> [--json] | Rename a session and move its auth data | | cdx login <name> [--json] | Re-authenticate a session (logout + login) | | cdx logout <name> [--json] | Log out of a session | | cdx rmv <name> [--force] [--json] | Remove a session and its auth data (prompts for confirmation unless --force) | | cdx clean [name] [--json] | Clear launch transcript logs for one session or all sessions | | cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR] [--force] [--json] | Export sessions to a portable bundle; --include-auth encrypts auth data with a passphrase | | cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json] | Import sessions from a bundle into the current CDX_HOME | | cdx doctor [--json] | Inspect CLI dependencies, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines | | cdx repair [--dry-run] [--force] [--json] | Plan or apply safe repairs for missing state files, quarantines, and orphan profiles | | cdx update [--check] [--yes] [--json] [--version TAG] | Update cdx-manager using the installer that matches how it was installed | | cdx notify <name> --at-reset [--poll seconds] [--once] [--json] | Wait for a session reset time and send a desktop notification when due | | cdx notify --next-ready [--poll seconds] [--once] [--json] | Wait until the recommended session is usable or needs a refresh after reset | | cdx status [--json] [--refresh] | Show token usage table for all sessions; JSON returns a versioned payload with structured warnings | | cdx status --small [--refresh] / cdx status -s [--refresh] | Show compact token usage table without provider, blocking quota, credits, and updated columns | | cdx status <name> [--json] [--refresh] | Show detailed usage breakdown for one session | | cdx --help | Show usage | | cdx --version | Show version |

JSON Output

cdx-manager can be consumed by other apps through its CLI JSON contract.

Commands with machine-readable output:

• cdx --json
• cdx status --json
• cdx status <name> --json
• cdx add ... --json
• cdx cp ... --json
• cdx ren ... --json
• cdx rmv ... --json
• cdx clean ... --json
• cdx export ... --json
• cdx import ... --json
• cdx login ... --json
• cdx logout ... --json
• cdx doctor --json
• cdx repair --json
• cdx update --json
• cdx notify ... --json

Success payloads follow a shared envelope:

{
  "schema_version": 1,
  "ok": true,
  "action": "add",
  "message": "Created session work (codex)",
  "warnings": [],
  "session": {
    "name": "work"
  }
}

Errors use a shared stderr JSON envelope whenever --json is present:

{
  "schema_version": 1,
  "ok": false,
  "error": {
    "code": "invalid_usage",
    "message": "Usage: cdx status [--json] [--refresh] | ...",
    "exit_code": 1
  }
}

status --json and similar commands also use the same envelope and place non-fatal issues in warnings instead of mixing plain-text diagnostics into stderr.

This makes cdx-manager usable from editor plugins, scripts, and desktop apps without scraping human-readable terminal output.

Backup And Restore

You can move sessions between machines with portable bundles:

cdx export backup.cdx
cdx import backup.cdx

To migrate auth and avoid logging in again, include auth data in an encrypted bundle:

export CDX_BUNDLE_PASSPHRASE='choose-a-strong-passphrase'
cdx export backup-auth.cdx --include-auth --passphrase-env CDX_BUNDLE_PASSPHRASE
cdx import backup-auth.cdx --passphrase-env CDX_BUNDLE_PASSPHRASE

Notes:

• --include-auth is encrypted and requires a passphrase.
• Without --passphrase-env, cdx prompts in an interactive terminal.
• --sessions work,perso exports or imports only a subset.
• --force allows overwriting existing destination sessions during import or replacing an existing bundle file during export.
• Auth bundles contain credentials. Treat them like secrets and delete them after transfer.

Available Scripts

• npm test: run the Python test suite
• npm run test:py: run the Python unit tests through the portable launcher
• npm run lint: check the Node launcher and byte-compile the Python sources and tests
• npm run link: link cdx globally for local development (npm link)
• npm run unlink: remove the global link

Windows Support

• Supported install paths on Windows:
  • npm install -g cdx-manager
  • pipx install cdx-manager
  • uv tool install cdx-manager
  • install.ps1
• The npm launcher resolves Python via py -3, python, then python3, so a global npm install works even when python3.exe is missing.
• install.sh is Unix-only.
• make install and make uninstall are Unix-oriented convenience commands, not the default Windows path.
• cdx isolates Claude sessions on Windows by setting HOME, USERPROFILE, HOMEDRIVE, and HOMEPATH.
• Desktop notifications use PowerShell on Windows.
• Codex transcript capture is optional on Windows:
  • if a compatible script command is available and exposed via CDX_SCRIPT_BIN, cdx uses it
  • otherwise Codex launches without transcript capture and the session still works normally
• cdx doctor reports the transcript-capture fallback explicitly so missing script on Windows is visible without being treated as a hard failure.

Project Structure

bin/
  cdx.js                # Node launcher used by npm
  python-runner.js      # Shared Python resolver and process wrapper
  cdx                   # Python entrypoint invoked by the launcher

src/
  cli.py                # Top-level command router
  cli_commands.py       # Command handlers and argument handling
  cli_render.py         # Terminal formatting, tables, colors, and errors
  backup_bundle.py      # Portable session bundle encoding/decoding + auth encryption
  status_view.py        # Status table/detail rendering and priority ranking
  provider_runtime.py   # Provider launch/auth commands, transcripts, signals
  claude_refresh.py     # Claude usage refresh orchestration
  session_service.py    # Session lifecycle: create, copy, rename, launch, remove, status
                        # resolution, auth state management
  session_store.py      # JSON persistence layer: sessions.json + per-session
                        # state files
  status_source.py      # Status artifact discovery: scans JSONL history files
                        # and terminal log transcripts, strips ANSI sequences,
                        # extracts usage metrics via pattern matching
  config.py             # CDX_HOME resolution (env override or ~/.cdx)
  errors.py             # CdxError with optional exit code
  __init__.py           # Public Python exports

test/
  test_cli_py.py            # CLI command dispatch tests
  test_session_service_py.py  # Session service unit tests

Data Layout

All session data lives under CDX_HOME (default: ~/.cdx/):

~/.cdx/
  sessions.json             # Session registry (versioned, all sessions)
  state/
    <encoded-name>.json     # Per-session rehydration state
  profiles/
    <encoded-name>/         # Codex session: CODEX_HOME points here
      log/
        cdx-session.log     # Terminal transcript (written by script(1))
    <encoded-name>/
      claude-home/          # Claude session: HOME points here
        log/
          cdx-session.log

Session names are URL-encoded when used as directory or file names. CLI command names such as add, status, and login are reserved and cannot be used as session names.

Troubleshooting

• cdx <name> fails with "not authenticated" — run cdx login <name> first.
• cdx says no compatible Python 3 interpreter was found — install Python 3 and make py -3, python, or python3 available on PATH.
• cdx add succeeds but the session does not appear — check that CDX_HOME is consistent between calls; a mismatch creates two separate registries.
• Status shows n/a for all fields — the session has not been launched yet, or the provider has not written any status output to its history files. Launch the session and run /status inside it at least once.
• cdx rmv says "Removal requires confirmation in an interactive terminal" — pass --force to bypass the prompt in non-interactive environments (scripts, CI).
• cdx login hangs — the provider's login flow requires a browser or device code. Follow the on-screen instructions in the terminal that opened.
• make install says npm link is not found — ensure Node.js and npm are installed and in your PATH.
• On Windows, doctor warns that script is missing — this is expected on many setups. Codex still launches, but transcript capture stays disabled unless you point CDX_SCRIPT_BIN to a compatible wrapper.

Contributing

Contribution guidelines are available in CONTRIBUTING.md.

License

This project is licensed under the MIT License. See LICENSE.