Codex Mate

Local-first CLI + Web UI that edits your AI tool configs and sessions directly on disk, with built-in usage analytics and safe rollback.

Docs · Quick Start · Commands · Web UI · MCP · 中文

What Is This?

Codex Mate is a local-first CLI + Web UI for unified management of:

Codex provider/model switching and config writes
Claude Code profiles (writes to ~/.claude/settings.json)
Claude Code CLAUDE.md editing (writes to ~/.claude/CLAUDE.md)
OpenClaw JSON5 profiles and workspace AGENTS.md
Local skills market for Codex / Claude Code (target switching, local skills management, cross-app import, ZIP distribution)
Local Codex/Claude/Gemini CLI/CodeBuddy Code sessions (list/filter/export/delete) with Usage analytics overview
Plugins (Prompt templates): reusable templates with variables and one-click copy
Task orchestration: plan/queue/run/review local tasks

It works on local files directly and does not require cloud hosting. The skills market is also local-first: it operates on local directories and does not depend on a remote marketplace.

Comparison

Dimension	Codex Mate	Manual File Editing
Multi-tool management	Codex + Claude Code + OpenClaw in one entry	Different files and folders per tool
Operation mode	CLI + local Web UI	Manual TOML/JSON/JSON5 edits
Session handling	Browse/filter/Usage analytics/export/batch cleanup	Manual file location and processing
Skills reuse	Local skills market + cross-app import + ZIP distribution	Manual folder copy and reconciliation
Operational visibility	Unified view of config, sessions, and Usage summaries	Depends on manual file inspection and scattered commands
Rollback readiness	Backup before first takeover	Easy to overwrite by mistake
Automation integration	MCP stdio (read-only by default)	Requires custom scripting

Core Features

Configuration

Provider/model switching (switch, use)
Codex config.toml template confirmation before write
Claude Code profile management and apply
Claude Code CLAUDE.md editing (writes to ~/.claude/CLAUDE.md)
OpenClaw JSON5 profile management

Session Management

Unified Codex + Claude + Gemini CLI + CodeBuddy Code session list
Session locations (local-first, configurable):
- Codex: ~/.codex/sessions/*.jsonl (or $CODEX_HOME/sessions, $XDG_CONFIG_HOME/codex/sessions)
- Claude: ~/.claude/projects/**/**/*.jsonl (or $CLAUDE_HOME/projects, $XDG_CONFIG_HOME/claude/projects)
- Gemini: ~/.gemini/tmp/*/chats/*.json (or $GEMINI_HOME/tmp, $XDG_CONFIG_HOME/gemini/tmp)
- CodeBuddy: ~/.codebuddy/projects/**/**/*.jsonl (or $CODEBUDDY_CODE_HOME_DIR/projects)
Local session pinning with persistent pinned state and pinned-first ordering
Keyword/source/cwd/role/time filters, plus shareable filter links
Copy resume command (Codex/Gemini/CodeBuddy): codex resume <sessionId> / gemini -r <sessionId> / codebuddy -r <sessionId>
Fast search UX: short-lived query result caching to avoid rescanning on each keystroke
Usage subview with 7d / 30d session trends, message trends, source share, and top paths
Markdown export (Web UI + codexmate export-session, supports --session-id or --file)
Session-level and message-level delete (supports batch), with a local recycle bin for restore/purge
Large-session preview optimization (fast tail preview path)

Skills Market

Switch the skills install target between Codex and Claude Code
Inspect local installed skills, root paths, and status
Scan importable sources from Codex / Claude Code / Agents
Support cross-app import, ZIP import/export, and batch delete

Plugins

Prompt templates: save, edit, and reuse prompts with variables
Compose + copy workflow for fast prompt iteration (stored locally in browser storage)

Engineering Utilities

MCP stdio domains (tools, resources, prompts)
Automation hooks (/hooks/*) + outbound webhook notifiers
Built-in proxy controls (proxy)
Auth profile management (auth)
Zip/unzip utilities

Automation (signal → action)

When running codexmate run, you can accept external webhooks and convert them into queued tasks:

Webhook entry: POST /hooks/<source> (currently github, gitlab)
Rule config: ~/.codex/codexmate-automation.json
Supported action: task.queue.add (optionally startQueue: true)
Notifications: notifiers[] supports type: "webhook" for Slack/Feishu-style incoming webhooks

Architecture

At a glance (what it does → what you get)

flowchart LR
    subgraph You["You"]
      CLI["CLI"]
      WEB["Web UI"]
      MCP["MCP (stdio)"]
    end

    subgraph Mate["Codex Mate (local control panel)"]
      API["Local HTTP API"]
      CFG["Config management"]
      SESS["Sessions & Usage"]
      SKL["Skills management"]
      PLG["Plugins: Prompt templates"]
    end

    subgraph Files["Local files only (auditable & reversible)"]
      CODEX["~/.codex/*"]
      CLAUDE["~/.claude/settings.json + CLAUDE.md"]
      OPENCLAW["~/.openclaw/*.json5 + ~/.openclaw/openclaw.json + workspace/AGENTS.md"]
      SKILLS["~/.{codex,claude,agents}/skills"]
      STATE["sessions / usage / trash / runs"]
      BROWSER["Browser storage (templates)"]
    end

    CLI --> API
    WEB --> API
    MCP --> API
    WEB --> PLG

    API --> CFG
    API --> SESS
    API --> SKL
    PLG --> BROWSER

    CFG --> CODEX
    CFG --> CLAUDE
    CFG --> OPENCLAW
    SKL --> SKILLS
    SESS --> STATE

Capability → Local target → Outcome

Capability	Local target	What you get
Config management (Codex / Claude / OpenClaw)	`~/.codex/`, `~/.claude/settings.json`, `~/.claude/CLAUDE.md`, `~/.openclaw/`	Faster provider/model switching, multi-profile management, safer writes with backups
Sessions & Usage	sessions / usage aggregates / trash	Quickly locate sessions, filter/export, batch cleanup, and view trends
Skills market	`~/.{codex,claude,agents}/skills`	Local install/import/export (ZIP), cross-app reuse
Plugins (Prompt templates)	Browser storage	Reusable prompt templates with variables and one-click copy
MCP (stdio)	local API + file operations	Integrate with external tools under controllable permissions (read-only by default)

Quick Start

Install from npm

npm install -g codexmate
codexmate setup
codexmate status
codexmate run

Default listen address is 0.0.0.0:3737 for LAN access, and browser auto-open is enabled by default.

Safety note: the unauthenticated management UI is exposed to your current LAN by default. Use trusted networks only; for local-only access, set CODEXMATE_HOST=127.0.0.1 or pass --host 127.0.0.1.

Install Codex CLI / Claude Code CLI (optional)

Codex Mate can pass through to the official CLIs (e.g. codexmate codex ...). Install them first:

# Codex CLI (default)
npm install -g @openai/codex

# Codex CLI on Termux (Android)
npm install -g @mmmbuto/codex-cli-termux@latest

# Claude Code
npm install -g @anthropic-ai/claude-code

# Gemini CLI
npm install -g @google/gemini-cli

# CodeBuddy Code
npm install -g @tencent-ai/codebuddy-code

Run from source

git clone https://github.com/SakuraByteCore/codexmate.git
cd codexmate
npm install
npm start run

Tests / CI (service only)

npm start run --no-browser

Convention: automated tests validate service and API behavior only, without opening browser pages.

Developer helper scripts

npm run reset
npm run reset 79

npm run reset: reset to default origin/main
npm run reset 79: sync directly to the latest head snapshot of PR #79
The script also handles local branch switching, workspace cleanup, untracked file cleanup, and final state validation

Command Reference

Command	Description
`codexmate status`	Show current config status
`codexmate setup`	Interactive setup
`codexmate list` / `codexmate models`	List providers / models
`codexmate switch <provider>` / `codexmate use <model>`	Switch provider / model
`codexmate add <name> <URL> [API_KEY]`	Add provider
`codexmate delete <name>`	Delete provider
`codexmate claude <BaseURL> <API_KEY> [model]`	Write Claude Code config
`codexmate auth <list\|import\|switch\|delete\|status>`	Auth profile management
`codexmate workflow <list\|get\|validate\|run\|runs>`	MCP workflow management
`codexmate codex [args...] [--follow-up <text> repeatable]`	Codex CLI passthrough entrypoint (auto-adds `--yolo`, supports queued follow-up appends)
`codexmate qwen [args...]`	Qwen CLI passthrough entrypoint
`codexmate run [--host <HOST>] [--no-browser]`	Start Web UI
`codexmate mcp serve [--read-only\|--allow-write]`	Start MCP stdio server
`codexmate export-session --source <codex\|claude\|gemini\|codebuddy> ...`	Export session to Markdown
`codexmate zip <path> [--max:0-9]` / `codexmate unzip <zip> [out]`	Zip / unzip
`codexmate unzip-ext <zip-dir> [out] [--ext:suffix[,suffix...]] [--no-recursive]`	Extract files with target suffixes from ZIP files in a directory (default `.json`, recursive by default)

Codex Follow-up Append (Optional)

codexmate codex --follow-up "scan repository first" --follow-up "then fix failing tests"
codexmate codex --model gpt-5.3-codex --follow-up "step1" --follow-up "step2"

Note: both --follow-up and --queued-follow-up are accepted and repeatable.

Web UI

Codex Mode

Provider/model switching
Model list management
~/.codex/AGENTS.md editing

Claude Code Mode

Multi-profile management
Default write to ~/.claude/settings.json
~/.claude/CLAUDE.md editing
Shareable import command copy

OpenClaw Mode

JSON5 multi-profile management
Apply to ~/.openclaw/openclaw.json
Manage ~/.openclaw/workspace/AGENTS.md

Plugins Mode (Prompt Templates)

Entry: switch to Plugins → Prompt Templates
Manage custom templates (JSON import/export)
Variables: in Manage, you can “Add variable” (inserts {{var}}) and fill variable values in the Variables panel
Generate & copy: after filling variables, copy the final rendered prompt from Preview
Built-in template: ships a single read-only template for light code-comment polishing

Sessions Mode

Unified Codex + Claude sessions
Browser / Usage subview switching
Local pin/unpin with persistent storage and pinned-first ordering
Search, filter, export, delete, batch cleanup
Usage view includes 7d / 30d session trends, message trends, source share, and top paths

Skills Market Tab

Switch the skills install target between Codex and Claude Code
Show the current local skills root, installed items, and importable items
Scan importable sources under Codex / Claude Code / Agents
Support cross-app import, ZIP import/export, and batch delete

MCP

Transport: stdio

Default: read-only tools
Enable writes: --allow-write or CODEXMATE_MCP_ALLOW_WRITE=1
Domains: tools, resources, prompts

Examples:

codexmate mcp serve --read-only
codexmate mcp serve --allow-write

Config Files

~/.codex/config.toml
~/.codex/auth.json
~/.codex/models.json
~/.codex/provider-current-models.json
~/.claude/settings.json
~/.claude/CLAUDE.md
~/.openclaw/openclaw.json
~/.openclaw/workspace/AGENTS.md

Environment Variables

Variable	Default	Description
`CODEXMATE_PORT`	`3737`	Web server port
`CODEXMATE_HOST`	`0.0.0.0`	Web listen host (set `127.0.0.1` for local-only access)
`CODEXMATE_NO_BROWSER`	unset	Set `1` to disable browser auto-open
`CODEXMATE_MCP_ALLOW_WRITE`	unset	Set `1` to allow MCP write tools by default
`CODEXMATE_FORCE_RESET_EXISTING_CONFIG`	`0`	Set `1` to force bootstrap reset of existing config

Tech Stack

Node.js
Vue.js 3 (Web UI)
Native HTTP server
@iarna/toml, json5

Contributing

Issues and pull requests are accepted.

License

Apache-2.0

Claude Code Mode

Multi-profile management
Default write to ~/.claude/settings.json
~/.claude/CLAUDE.md editing
Shareable import command copy

OpenClaw Mode

JSON5 multi-profile management
Apply to ~/.openclaw/openclaw.json
Manage ~/.openclaw/workspace/AGENTS.md

Sessions Mode

Unified Codex + Claude sessions
Browser / Usage subview switching
Local pin/unpin with persistent storage and pinned-first ordering
Search, filter, export, delete, batch cleanup
Usage view includes 7d / 30d session trends, message trends, source share, and top paths

Skills Market Tab

Switch the skills install target between Codex and Claude Code
Show the current local skills root, installed items, and importable items
Scan importable sources under Codex / Claude Code / Agents
Support cross-app import, ZIP import/export, and batch delete

MCP

Transport: stdio

Default: read-only tools
Enable writes: --allow-write or CODEXMATE_MCP_ALLOW_WRITE=1
Domains: tools, resources, prompts

Examples:

codexmate mcp serve --read-only
codexmate mcp serve --allow-write

Config Files

~/.codex/config.toml
~/.codex/auth.json
~/.codex/models.json
~/.codex/provider-current-models.json
~/.claude/settings.json
~/.claude/CLAUDE.md
~/.openclaw/openclaw.json
~/.openclaw/workspace/AGENTS.md

Environment Variables

Variable	Default	Description
`CODEXMATE_PORT`	`3737`	Web server port
`CODEXMATE_HOST`	`0.0.0.0`	Web listen host (set `127.0.0.1` for local-only access)
`CODEXMATE_NO_BROWSER`	unset	Set `1` to disable browser auto-open
`CODEXMATE_MCP_ALLOW_WRITE`	unset	Set `1` to allow MCP write tools by default
`CODEXMATE_FORCE_RESET_EXISTING_CONFIG`	`0`	Set `1` to force bootstrap reset of existing config

Tech Stack

Node.js
Vue.js 3 (Web UI)
Native HTTP server
@iarna/toml, json5

Contributing

Issues and pull requests are accepted.

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 829 Commits
.github		.github
cli		cli
lib		lib
plugins		plugins
site		site
tests		tests
tools		tools
web-ui		web-ui
.coderabbit.yaml		.coderabbit.yaml
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.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

What Is This?

Comparison

Core Features

Automation (signal → action)

Architecture

At a glance (what it does → what you get)

Capability → Local target → Outcome

Quick Start

Install from npm

Install Codex CLI / Claude Code CLI (optional)

Run from source

Tests / CI (service only)

Developer helper scripts

Command Reference

Codex Follow-up Append (Optional)

Web UI

Codex Mode

Claude Code Mode

OpenClaw Mode

Plugins Mode (Prompt Templates)

Sessions Mode

Skills Market Tab

MCP

Config Files

Environment Variables

Tech Stack

Contributing

License

Claude Code Mode

OpenClaw Mode

Sessions Mode

Skills Market Tab

MCP

Config Files

Environment Variables

Tech Stack

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 23

Contributors

Uh oh!

Languages