Codex Mate

A lightweight AI configuration assistant: quickly switch Codex providers/models and Claude Code configs, with a unified session browser

English · 中文版

Overview

One tool to switch Codex/Claude Code providers & models and manage/browse local sessions in one click.

What You Get

One-command provider/model switching
Local config control with backups
Lightweight Web UI instead of heavy clients
Unified session browser (view/export/resume when available)
Session management: list/filter/export/delete local sessions; keyword search supports Codex and Claude
New in 0.0.9: Claude sessions are searchable by keywords (e.g., claude code, claude-code, numeric tokens)

Feature Overview

Module	Problem	Key Capabilities
Codex Config	Switching providers/models is painful	Provider/model switching, model management, CLI + Web entry points, template-confirmed writes
Claude Code Config	Multiple profiles and inconsistent write paths	Profile management, default write to `~/.claude/settings.json`
OpenClaw Config	OpenClaw configs are scattered	JSON5 profiles, apply to `~/.openclaw/openclaw.json`, AGENTS workspace management
Session Browser	Local sessions are hard to track	List/filter sessions, keyword search (Codex + Claude), export to Markdown, copy resume command (when available), delete and batch cleanup
Utilities	Compression/extraction requires extra tools	7-Zip preferred, JS fallback

Why Codex Mate

Focused on three jobs: Codex provider/model switching + Claude Code config apply + OpenClaw config apply
Local-first: configs and API keys are written to local files, not the cloud
Lightweight: CLI + Web, no desktop app required
Reversible: auto-backup before first takeover

Use Cases

Frequent provider/model switching, want a one-command flow
Use both Codex and Claude Code, want a single entry point
Need to browse/export local Codex + Claude Code sessions and copy resume commands when available
Use OpenClaw with multiple profiles, want quick switching
Multi-project or multi-environment setups that need quick config changes
Want a visual UI without a heavy client

Scope and Boundaries

Only configuration management for Codex, Claude Code, and OpenClaw, not a full all-in-one tool suite
No built-in proxy/relay/billing dashboard/cloud sync (kept lightweight)
Web UI runs only when you start it (codexmate run)

30-Second Start (No Install)

npx codexmate@latest status

npx codexmate@latest run

Then open http://localhost:3737 in your browser.

Quick Start

Install (global):

npm install -g codexmate

Or run once without install:

npx codexmate@latest status

Run the interactive setup:

codexmate setup

Check status:

codexmate status

Start the Web UI:

codexmate run

Then open http://localhost:3737 in your browser.

Alternatives

cc-switch: https://github.com/farion1231/cc-switch

Install

Global (Recommended)

npm install -g codexmate

Package name on npm: codexmate.

Want to update to the latest effects features each time? Install from GitHub (re-run to update):

npm install -g ymkiux/codexmate

Run with npx (No Install)

npx codexmate@latest status

npx codexmate@latest run

From Source

git clone https://github.com/ymkiux/codexmate.git
cd codexmate
npm install
npm link

Requirements

Node.js >= 14
Windows / macOS / Linux

CLI Cheat Sheet

Command	Description
`codexmate`	Show help and available commands
`codexmate setup`	Interactive configuration wizard
`codexmate status`	Show current status
`codexmate list`	List all providers
`codexmate switch <provider>`	Switch provider
`codexmate use <model>`	Switch model
`codexmate add <name> <URL> [API key]`	Add a provider
`codexmate delete <provider>`	Delete a provider
`codexmate claude <BaseURL> <API key> [model]`	Write Claude Code config to `~/.claude/settings.json`
`codexmate models`	List all models
`codexmate add-model <model>`	Add a model
`codexmate delete-model <model>`	Delete a model
`codexmate run`	Start the Web UI
`codexmate export-session --source <codex	claude> (--session-id

Web UI

Start the Web UI (auto opens browser):

codexmate run

Codex Config Mode

View current provider and model status
Quickly switch provider and model
Manage available model list
Edit ~/.codex/AGENTS.md instruction file (same level as config.toml)
Add/delete custom providers
Supports Codex config management on Linux/Windows

Claude Code Config Mode (Windows / macOS / Linux)

Manage multiple Claude Code profiles
Configure API key, Base URL, and model
Default write to env in ~/.claude/settings.json: env.ANTHROPIC_API_KEY / env.ANTHROPIC_BASE_URL / env.ANTHROPIC_MODEL
One-liner apply via CLI:

codexmate claude https://api.example.com/v1 sk-ant-xxx claude-3-7-sonnet

In the Web UI, each Claude configuration card now has a "Share Import Command" button that copies a one-click import command (for example: codexmate claude <BaseURL> <API Key> <Model>).

OpenClaw Config Mode

Manage multiple OpenClaw JSON5 profiles
Apply to ~/.openclaw/openclaw.json
Manage AGENTS.md under the OpenClaw Workspace (default: ~/.openclaw/workspace/AGENTS.md)

Session Browser

View local Codex and Claude Code sessions in one page
Filter by source (Codex / Claude / All)
Filter by session path (cwd), auto refresh on selection
Export selected sessions to Markdown
Copy resume command when available
Delete single sessions (local jsonl records)
Batch delete multiple sessions with partial failure summary
Delete individual records or multi-select within session details (writes back to original jsonl)

Codex Template Confirmation Mode

Codex config changes in Web UI go to a config.toml template editor first
Only writes to config.toml after you click "Confirm Apply Template"
Prevents direct one-click overwrites from the UI

Configuration Files

Config directory: ~/.codex/

config.toml - Codex main config
auth.json - API auth info
models.json - Available model list
provider-current-models.json - Per-provider current model config
codexmate-init.json - First-run marker
config.toml.codexmate-backup-*.bak - Backup created on first takeover

Claude Code config files:

~/.claude/settings.json - Runtime config (default write target)
~/.claude/settings.json.codexmate-backup-*.bak - Backup before first overwrite

OpenClaw config files:

~/.openclaw/openclaw.json - OpenClaw config (JSON5)
~/.openclaw/workspace/AGENTS.md - OpenClaw workspace instructions

First Run Initialization

When you run codexmate for the first time and an existing ~/.codex/config.toml is detected that is not managed by Codex Mate:

The original file is backed up as config.toml.codexmate-backup-<timestamp>.bak
The original config.toml is preserved, and a first-run marker is written
Only when CODEXMATE_FORCE_RESET_EXISTING_CONFIG=1 is set will the default config be rebuilt
Subsequent runs will not repeat this process

Examples

Add a Custom API Provider

codexmate add myapi https://api.example.com/v1 sk-your-api-key
codexmate switch myapi

Switch to a Different Model

codexmate use gpt-4-turbo

Export a Session (CLI)

codexmate export-session --source codex --session-id 123456
codexmate export-session --source claude --file "~/.claude/projects/demo/session.jsonl" --max-messages=all

By default, exports are capped at 1000 messages. Use --max-messages=all (or Infinity) to export everything.

Configure Claude Code (Cross-Platform)

Start the Web UI: codexmate run
Switch to "Claude Code Config" mode in the browser
Add a profile (example Zhipu GLM): Name=ZhipuGLM, API Key=your API key, Base URL=https://open.bigmodel.cn/api/anthropic, Model=glm-4.7
Click the card to apply, or use "Save & Apply to Claude Config" in the editor
Default write to ~/.claude/settings.json
Restart Claude Code to apply

Start the Web UI

codexmate run

By default it binds to 127.0.0.1. To expose on LAN, use --host or CODEXMATE_HOST:

codexmate run --host 0.0.0.0

Then open http://localhost:3737 (or your chosen host). Note: binding to 0.0.0.0 is unsafe on untrusted networks.

FAQ

Q: Which operating systems are supported?

A: Codex features support Windows and Linux (CLI and Web). Claude Code config applies to Windows / macOS / Linux (writes to ~/.claude/settings.json).

Q: Where are API keys stored?

A: API keys are stored locally in ~/.codex/config.toml and are not uploaded.

Q: Is the Web UI safe?

A: The Web UI runs locally; all operations happen on your machine. API keys are masked in the UI.

Q: How do Claude Code configs take effect?

A: After clicking "Apply to Claude Config", it writes to ~/.claude/settings.json. Restart Claude Code to apply.

Q: How to uninstall?

A: Run npm uninstall -g codexmate.

Extras: Compression/Extraction

Prefer 7-Zip for multithreaded zip/unzip. Fallback to the built-in JS library when unavailable.

# Compress file or folder (default compression level 5)
codexmate zip <path>

# Set compression level (0-9, 0=store only, 9=max)
codexmate zip <path> --max:9

# Unzip a zip file (default to same-level folder)
codexmate unzip <zip path>

# Unzip to a specific output directory
codexmate unzip <zip path> <output dir>

Examples:

# Compress a project folder
codexmate zip ./my-project

# Max compression
codexmate zip ./my-project --max:9

# Store only (fast)
codexmate zip ./large-folder --max:0

# Unzip
codexmate unzip ./my-project.zip

# Unzip to a target location
codexmate unzip ./backup.zip D:/restored

Note: 7-Zip is optional. If missing, the built-in JS library is used. --max only applies to 7-Zip.

Tech Stack

Node.js - Runtime
@iarna/toml - TOML parser
Vue.js 3 - Web UI framework
Native HTTP - Built-in Web server

Release (GitHub Actions)

Create a tag that matches package.json (for example v0.0.8). Then run the release workflow in GitHub Actions and input that tag. It will create a GitHub Release and attach the npm pack .tgz artifact.

License

Contributing

Issues and pull requests are welcome.

Changelog

See doc/CHANGELOG.md for the English version. See doc/CHANGELOG.zh-CN.md for the Chinese version.

Made with ymkiux

Name		Name	Last commit message	Last commit date
Latest commit History 179 Commits
.github		.github
cmd		cmd
doc		doc
lib		lib
res		res
scripts		scripts
tests		tests
web-ui		web-ui
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
cli.js		cli.js
package-lock.json		package-lock.json
package.json		package.json
web-ui.html		web-ui.html

Folders and files

Latest commit

History

Repository files navigation

Codex Mate

Overview

What You Get

Feature Overview

Why Codex Mate

Use Cases

Scope and Boundaries

30-Second Start (No Install)

Quick Start

Alternatives

Install

Global (Recommended)

Run with npx (No Install)

From Source

Requirements

CLI Cheat Sheet

Web UI

Codex Config Mode

Claude Code Config Mode (Windows / macOS / Linux)

OpenClaw Config Mode

Session Browser

Codex Template Confirmation Mode

Configuration Files

First Run Initialization

Examples

Add a Custom API Provider

Switch to a Different Model

Export a Session (CLI)

Configure Claude Code (Cross-Platform)

Start the Web UI

FAQ

Q: Which operating systems are supported?

Q: Where are API keys stored?

Q: Is the Web UI safe?

Q: How do Claude Code configs take effect?

Q: How to uninstall?

Extras: Compression/Extraction

Tech Stack

Release (GitHub Actions)

License

Contributing

Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages