codx-hub

Manage Codex CLI profiles, hooks, and sessions — one tool, all in one place.

Note: macOS, Linux, and Windows supported.

Install

npm install -g codx-hub-cli

Quick Start

# Add a profile with single model
codx-hub profile add flow -m gpt-4o -t sk-... -u https://api.example.com

# Add a profile with multiple models
codx-hub profile add multi -m gpt-4o -m o3 -t sk-... -u https://api.example.com

# Set as default
codx-hub profile default flow

# Launch Codex CLI with it
codx-hub run

# Or launch with a specific profile
codx-hub run flow

Commands

Profiles

Manage multiple OpenAI API configurations (model, token, URL).

codx-hub profile add <name> -m <model> -t <token> -u <url>    # Add or update
codx-hub profile add <name> -m <m1> -m <m2> -t <token>        # Add with multiple models
codx-hub profile update <name> -m <model>                       # Update fields
codx-hub profile update <name> -m <m1> -m <m2>                  # Update with multiple models
codx-hub profile list                                           # List all (tokens masked)
codx-hub profile view <name>                                    # View details (token visible)
codx-hub profile view <name> -j                                 # View as JSON
codx-hub profile remove <name>                                  # Remove
codx-hub profile rename <oldName> <newName>                     # Rename
codx-hub profile default <name>                                 # Set default
codx-hub profile export <name>                                  # Export to settings file

Multi-Model Profiles:

You can specify multiple models per profile using the -m flag multiple times:

# Add a profile with multiple models
codx-hub profile add myprofile -m gpt-4o -m o3 -t <token> -u <url>

When you launch Codex CLI with codx-hub run, the first model is passed via --model.

Run / Use

Launch Codex CLI with a profile's credentials injected as environment variables.

# Set a profile as default
codx-hub use <name>

# Launch using the default profile
codx-hub run [extra args...]

# Launch with a specific profile
codx-hub run <name> [extra args...]

run execs into the codex CLI with OPENAI_API_KEY, OPENAI_BASE_URL, and --model set from the profile.

Hook

Manage Codex CLI hooks in ~/.codex/settings.json.

codx-hub hook list                                               # List all hooks
codx-hub hook add -e <event> -c <command> [-m <matcher>] [-a]   # Add a hook
codx-hub hook remove -i <index>                                  # Remove by index
codx-hub hook enable -i <index> [-i <index>]                     # Enable disabled hooks
codx-hub hook disable -i <index> [-i <index>]                    # Disable active hooks

Events: PreToolUse, PostToolUse, Notification, Stop, UserPromptSubmit, PermissionRequest

Examples:

# Desktop notification when Codex finishes (macOS)
codx-hub hook add -e Stop -c 'osascript -e "display notification \"Done\""'

# Desktop notification when Codex finishes (Windows PowerShell)
codx-hub hook add -e Stop -c 'powershell -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show(\"Codex Done\")"'

# Hook only for Bash tool usage
codx-hub hook add -e PreToolUse -m Bash -c 'echo "Running bash..."'

# Async hook
codx-hub hook add -e PostToolUse -c 'my-logger.sh' -a

Disabled hooks are kept in a pool and can be re-enabled later with hook enable.

Session

Browse and search Codex CLI session history from ~/.codex/projects/.

codx-hub session list [-n <limit>] [-s] [-j]                    # List projects
codx-hub session show <project> [-v]                             # Show sessions for a project
codx-hub session search <query> [-p <project>] [-n <n>] [-i]    # Search conversation history
codx-hub session ps                                              # Show active processes
codx-hub session stats                                           # Summary statistics
codx-hub session clean [-d <days>] [--dry-run]                   # Delete old sessions
codx-hub session troubleshoot <session> [-i]                     # Troubleshoot a session

Examples:

# List recent projects
codx-hub session list -n 10

# Show sessions with first message preview
codx-hub session show codx-hub -v

# Case-insensitive search
codx-hub session search "authentication" -i

# Preview what would be cleaned up
codx-hub session clean -d 60 --dry-run

Shell Completion

# zsh — add to ~/.zshrc
eval "$(codx-hub completion zsh)"

# bash — add to ~/.bashrc
eval "$(codx-hub completion bash)"

# PowerShell — add to $PROFILE
Invoke-Expression (& codx-hub completion powershell | Out-String)

Completes subcommands, profile names, and event types.

Logging

codx-hub writes structured logs to ~/.codex/codx-hub/logs/codx-hub-YYYY-MM-DD.log.

Log levels

Levels are ordered from most to least verbose:

| Level | Description | |---|---| | DEBUG | All service calls, file reads/writes, path encode/decode | | INFO | Command executions, profile launches | | WARN | JSON auto-fix events, backup restores | | ERROR | Thrown exceptions, upstream errors, uncaught exceptions/rejections |

The default level is INFO. To change it, add _codx_hub_logLevel to ~/.codex/settings.json:

{
  "_codx_hub_logLevel": "DEBUG"
}

Valid values: DEBUG, INFO, WARN, ERROR.

Viewing logs

# Tail today's log
tail -f ~/.codex/codx-hub/logs/codx-hub-$(date +%Y-%m-%d).log

# View all logs
ls -lt ~/.codex/codx-hub/logs/

# Search for errors
grep ERROR ~/.codex/codx-hub/logs/*.log

Configuration

codx-hub reads from these paths (overridable via environment variables):

| File | Default | Env Override | |---|---|---| | Profiles | ~/.codex/profiles.json | CODEX_PROFILES_FILE | | Settings | ~/.codex/settings.json | CODEX_SETTINGS_FILE | | Codex dir | ~/.codex | CODEX_DIR |

Profile storage format

Single-model profile:

{
  "profiles": {
    "flow": {
      "model": "gpt-4o",
      "token": "sk-...",
      "url": "https://example.com/api"
    }
  },
  "default": "flow"
}

Multi-model profile:

{
  "profiles": {
    "multi": {
      "model": "gpt-4o",
      "models": ["gpt-4o", "o3"],
      "token": "sk-...",
      "url": "https://api.example.com"
    }
  },
  "default": "multi"
}

When launching with a multi-model profile, codx-hub uses the first model as the default via --model.

License

MIT