CDX Manager

Run multiple Codex, Claude, Antigravity, and Ollama 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.

What it does

Multiple providers, one tool. Register as many Codex, Claude, Antigravity, or Ollama sessions as you need. Codex and Claude get isolated auth environments; Antigravity is launchable through agy with OS-keyring auth; Ollama runs local models through ollama run.
Instant launch. cdx work opens your "work" session. cdx personal opens another. No config files to edit mid-flow.
Quick relaunch. cdx last reopens the most recently launched assistant profile.
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, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
Next-ready notification. cdx ready schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
Session control. Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
Persistent launch settings. Pin per-session power, permission, and fast-mode preferences once; cdx reapplies them on every launch until you unset them.
Launch history. Inspect recent launches with provider, result, duration, working directory, launch settings, and transcript path.
Update prompts. Periodic update checks surface cdx update directly in the cdx, cdx status, and launch output when a newer release is available.
Shared handoff context. Keep a per-workspace Markdown context, or build one from a source session transcript, and install it into another assistant session before switching providers or accounts.
Passive status resolution. Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
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+.
Environment isolation per session:
- Codex sessions override CODEX_HOME to a dedicated profile directory.
- Claude sessions override HOME to a dedicated profile directory and disable Claude Code commit co-author attribution by default.
- Antigravity sessions launch agy with a dedicated HOME for file-based settings; Google account credentials may still be stored in the OS keyring by Antigravity itself.
- Ollama sessions use the local Ollama server and launch ollama run <model>; set a model with cdx set <name> --model <model>.
- 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.
- Per-workspace shared context at ~/.cdx/contexts/<workspace-hash>/context.md.
- 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.
- Codex live source: codex app-server JSON-RPC account/rateLimits/read, normalized into 5-hour, weekly, reset, credit, and plan fields.
- 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.
On Linux, transcript capture uses the util-linux script -c command form.
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, claude, agy, and/or ollama 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.
# Set CDX_ALLOW_UNVERIFIED=1 only if you intentionally accept an unverified archive.
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.
# Set CDX_ALLOW_UNVERIFIED=1 only if you intentionally accept an unverified archive.
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.7.6 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.
If no checksum is available, standalone installers fail closed unless CDX_ALLOW_UNVERIFIED=1 is set.
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

# Register an Ollama session
cdx add ollama local --model llama3.2

# List all sessions
cdx

# Launch a session
cdx work

# Check usage across all sessions
cdx status

# Pick the best session using the same priority logic as status
cdx next

# Notify when the next cooling-down assistant is ready
cdx ready

Next-Ready Notifications

Use cdx ready when every useful assistant is cooling down and you want your terminal back. It is shorthand for cdx notify --schedule --next-ready: cdx picks the next known reset, registers a native OS notification, and exits immediately.

cdx ready
cdx ready --refresh

Persistent Launch Settings

New sessions start with power=medium and fast=off, so launches are predictable without enabling fast mode. Set or override only the values you want to pin:

cdx set work --power medium --permission full --fast off
cdx set personal --power low --permission review
cdx set --sessions all --permission auto
cdx set --provider ollama --model llama3.2
cdx set work --priority 80
cdx set work --rtk on
cdx power all low
cdx perm provider:claude review
cdx model provider:ollama llama3.2
cdx config work
cdx configs

Those values are stored on the session and reapplied every time you run cdx work. Remove overrides to return to provider-native defaults:

cdx unset work --power
cdx unset --sessions work,personal --fast
cdx unset --provider claude --permission
cdx unset work --priority
cdx unset work --rtk
cdx unset work --all
cdx power all default
cdx model provider:ollama default

--model maps to Codex --model, Claude --model, and Ollama ollama run <model>. --power maps to Codex model_reasoning_effort and Claude --effort. --permission maps to provider-native permission flags. --fast on clears the stored power setting and uses low effort; setting --power again disables fast mode. --priority is a 0..100 selector preference used as a tie-breaker after readiness and availability. --rtk on injects a launch instruction that encourages assistants to use RTK (rtk <command>) for noisy terminal commands when RTK is available, while keeping raw commands for exact output.

Launch History

Every interactive cdx <name> launch is recorded under CDX_HOME, including success/failure, duration, cwd, launch settings, and transcript path.

cdx history
cdx history work
cdx history work --limit 5
cdx history work --json
cdx history --summary
cdx history --summary --since 7d
cdx history --summary --from 2026-05-01 --to 2026-05-28

cdx history --summary aggregates total time per assistant. Add --since, --from, or --to to focus on a period.

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> [--model MODEL] [--json]`	Register a new session (`provider`: `codex`, `claude`, `antigravity`, or `ollama`; Ollama requires `--model`)
`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 disable <name> [--json]`	Disable a session without deleting it; disabled sessions stay visible and cannot launch
`cdx enable <name> [--json]`	Re-enable a disabled session
`cdx config <name> [--json]`	Show persistent launch settings for a session
`cdx configs [--json]`	Show persistent launch settings for all sessions in one table
`cdx power\|perm\|fast\|model <name\|all\|provider:PROVIDER\|a,b> <value\|default> [--json]`	Shortcut commands for setting or clearing one launch setting
`cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power low\|medium\|high\|xhigh\|max] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--model MODEL] [--priority 0..100] [--json]`	Persist launch settings for one or more sessions
`cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--rtk\|--model\|--priority\|--all) [--json]`	Remove persisted launch settings and fall back to provider defaults
`cdx history [name] [--limit N] [--summary] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]`	Show recent launch history or aggregate total launch time per assistant, optionally filtered by period
`cdx last [--json]`	Launch the most recent existing session from launch history
`cdx context show\|path\|init\|edit\|clear\|set [text...] [--json]`	Manage the shared Markdown context for the current workspace
`cdx handoff <name> [--json]`	Install the current workspace context into a target session and launch it unless `--json` is used
`cdx handoff <source> <target> [--json]`	Build shared context from the source session's latest launch transcript, install it into the target session, and launch the target unless `--json` is used; supports cross-provider handoff
`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 ready [--refresh] [--json]`	Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately
`cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]`	Wait for a session reset time or schedule an OS wake-up notification when due
`cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh] [--json]`	Wait until the recommended session is usable, or schedule the next known reset notification
`cdx next [--json] [--refresh]`	Select the best next assistant using the same priority logic as `cdx status`
`cdx select --provider PROVIDER [--min-reasoning-effort low\|medium\|high] [--min-power low\|medium\|high] [--require-ready] [--refresh] --json`	Select a suitable session for headless automation
`cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low\|medium\|high] [--power low\|medium\|high] [--permission MODE] [--timeout-seconds N] --json`	Run one headless task and return a stable JSON result
`cdx stats [name] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]`	Aggregate launch counts, duration, and known headless token usage by session
`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 disable ... --json
cdx enable ... --json
cdx context ... --json
cdx handoff ... --json
cdx history ... --json
cdx stats ... --json
cdx last --json
cdx doctor --json
cdx repair --json
cdx update --json
cdx ready --json
cdx notify ... --json
cdx select ... --json
cdx run ... --json

Success payloads follow a shared envelope:

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

Most commands use a shared stderr JSON envelope for errors 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. cdx run --json is the exception: it always writes one final JSON payload to stdout, including cdx-side and provider-start errors, so supervisors can parse a single result stream while provider stdout and stderr are captured to files.

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

Headless Runs

cdx run is designed for supervisors such as Orchestia. In --json mode, stdout contains only the final JSON payload; provider stdout and stderr are captured to files.

cdx run codex-work \
  --cwd /path/to/workspace \
  --prompt-file task_prompt.md \
  --model gpt-5.3-codex \
  --reasoning-effort low \
  --permission workspace-write \
  --timeout-seconds 1800 \
  --json

Use provider-based auto-selection when the caller wants cdx-manager to pick the account:

cdx run \
  --provider codex \
  --cwd /path/to/workspace \
  --prompt "Summarize the repo status." \
  --reasoning-effort low \
  --json

The result includes launcher: "cdx", run_id, selected session, provider, exit_code, duration_seconds, absolute transcript_path, stdout_path, stderr_path, and normalized usage token fields. Codex headless runs use codex exec --json; Claude headless runs use claude --print --output-format json. Token counts are null when the provider does not expose a supported JSON or JSONL usage shape.

Known headless token usage is persisted in launch history and can be aggregated later:

cdx stats --since 7d --json
cdx stats work

cdx select exposes the same session selection logic directly:

cdx select --provider codex --min-reasoning-effort low --require-ready --json

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, requires a passphrase, and exports only provider credential files rather than full profile caches or logs.
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
    launch_history.jsonl    # Append-only launch history
  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 Codex app-server rate-limit probe may be unavailable, the session may not be authenticated, and no legacy transcript/history status has been captured yet.
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.

Name		Name	Last commit message	Last commit date
Latest commit History 210 Commits
.github/workflows		.github/workflows
bin		bin
changelogs		changelogs
checksums		checksums
logics		logics
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
VERSION		VERSION
install.ps1		install.ps1
install.sh		install.sh
logics.yaml		logics.yaml
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CDX Manager

Table of Contents

What it does

Technical Overview

Getting Started

Prerequisites

Install

Environment

Quick Start

Next-Ready Notifications

Persistent Launch Settings

Launch History

All Commands

JSON Output

Headless Runs

Backup And Restore

Available Scripts

Windows Support

Project Structure

Data Layout

Troubleshooting

Contributing

License

About

Uh oh!

Releases 33

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

CDX Manager

Table of Contents

What it does

Technical Overview

Getting Started

Prerequisites

Install

Environment

Quick Start

Next-Ready Notifications

Persistent Launch Settings

Launch History

All Commands

JSON Output

Headless Runs

Backup And Restore

Available Scripts

Windows Support

Project Structure

Data Layout

Troubleshooting

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 33

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages