---

What is Codex Mate?

Have you ever felt overwhelmed by managing multiple local AI agents? Each has its own config format, session storage, and skills directory.

Codex Mate offers a unified control plane to bring order to the chaos. It's a local-first CLI + Web UI designed to manage Codex, Claude Code, OpenCode, and OpenClaw seamlessly.

What's So Special?

Unlike simple wrappers, Codex Mate acts as a Local Agent Bridge:

• Unified Session Browser: Search, inspect, filter, and export local sessions across Codex, Claude Code, Gemini CLI, and CodeBuddy Code from one place.
• OpenAI-Compatible Bridge: Use Codex with any OpenAI-compatible UI by normalizing the Responses API.
• Claude Provider Bridge: Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama through the built-in local Claude-compatible proxy.
• OpenCode Provider Control: Manage OpenCode provider/model selection with a CodexMate-owned provider store under ~/.codexmate, projecting only the active provider into native OpenCode config to avoid polluting or deleting user-owned settings.
• Skills Marketplace: A local-first market to share and import skills between different agent apps.
• Task Orchestrator: Plan and execute complex tasks with dependency tracking.

---

Current Progress

Feature	Status	Description
Provider Management	✅	Switch providers/models for Codex, Claude, OpenCode, and OpenClaw
Live Agent Sync	✅	Real-time monitoring of Codex/Claude config & status
Session Browser	✅	Search, preview, filter, and export sessions across Codex, Claude Code, Gemini CLI, and CodeBuddy Code
Usage Analytics	✅	Visualize message trends and top projects
Local Skills Market	✅	Cross-app import/export of agent skills
Task Queue	✅	DAG-based task execution and logs
OpenAI Bridge	✅	Convert Codex Responses API to standard OpenAI format
Claude Provider Bridge	✅	Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama via the built-in Claude-compatible proxy
OpenCode Provider Store	✅	Keep multiple OpenCode providers in ~/.codexmate while projecting only the selected provider to native OpenCode config
Prompt Templates	✅	Reusable prompt plugins with variables
MCP Integration	✅	Expose local tools and resources via MCP stdio
Auto Update	✅	Quick update CLI via codexmate update

---

Quick Start

Install via Homebrew (macOS / Linux)

brew tap SakuraByteCore/codexmate
brew install codexmate

Requires Node.js (brew install node if not present).

Install via npm

npm install -g codexmate
codexmate run

If the default Web UI port 3737 is unavailable, Codex Mate automatically tries the next ports (3738, 3739, ...). To force a fixed port, set CODEXMATE_PORT:

CODEXMATE_PORT=8080 codexmate run

Windows PowerShell:

$env:CODEXMATE_PORT=8080; codexmate run

Install via curl (Standalone)

curl -fsSL https://raw.githubusercontent.com/SakuraByteCore/codexmate/main/scripts/install.sh | bash

Supported Agents

• Codex: npm install -g @openai/codex
• Claude Code: npm install -g @anthropic-ai/claude-code
• Gemini CLI: npm install -g @google/gemini-cli
• CodeBuddy: npm install -g @tencent-ai/codebuddy-code
• OpenCode: install from the official OpenCode docs

---

Architecture

%%{ init: { 'flowchart': { 'curve': 'catmullRom' } } }%%
flowchart TD
    User([User])
    CLI[CLI]
    WebUI[Web UI]
    MCP[MCP Server]

    subgraph Mate [Codex Mate Core]
        API[HTTP API]
        Config[Config Engine]
        Session[Session Manager]
        Skills[Skills Market]
        Tasks[Task Runner]
    end

    subgraph Local [Local Filesystem]
        CodexDir[~/.codex]
        ClaudeDir[~/.claude]
        ClawDir[~/.openclaw]
        OpenCodeDir[~/.config/opencode]
        MateDir[~/.codexmate]
        State[Sessions/Usage/Trash]
    end

    User --> CLI & WebUI & MCP
    CLI & WebUI & MCP --> API

    API --> Config & Session & Skills & Tasks

    Config --> CodexDir & ClaudeDir & ClawDir & OpenCodeDir & MateDir
    Session --> State
    Skills --> Local

---

Special Thanks

Special thanks to all contributors for their contributions to Codex Mate ❤️

Star History

License

Apache-2.0