mimo2codex Documentation

mimo2codex is a local proxy designed to allow the latest OpenAI Codex CLI and desktop applications to communicate with virtually any modern Large Language Model (LLM). It acts as a protocol shim that translates between the Codex Responses API and upstream OpenAI Chat Completions-compatible APIs (such as Qwen, GLM, Kimi, vLLM, Ollama, or LM Studio) or native Responses APIs.

Key Capabilities:

• Protocol Translation: Translates Codex's Responses API $\leftrightarrow$ upstream Chat Completions on the fly.
• Multi-provider Routing: Routes requests to different providers (e.g., Xiaomi MiMo V2.5, DeepSeek V4 Pro, or generic providers) based on the model field in the request.
• Feature Support: Supports tool calling, web search (MiMo native web_search), vision, reasoning (including reasoning_content round-trips), and the MCP namespace.
• Admin Console: Provides a web interface at http://127.0.0.1:8788/admin/ for managing the model catalog, viewing chat logs, monitoring token stats, and configuring providers using SQLite persistence.

MiniMax requires specific request sanitization that other providers (like OpenAI or DeepSeek) do not. Instead of applying these changes globally, mimo2codex uses an opt-in system via the features object in the provider configuration.

Setting features.minimaxCompat: true automatically enables the following five sub-features:

• dropNullStrict: Removes tools[*].function.strict: null.
• dropNullContent: Removes content: null from assistant messages containing tool calls.
• dropToolChoiceAuto: Removes explicit tool_choice: "auto".
• mergeSystemMessages: Merges multiple role: "system" messages into a single message at the start of the array.
• extractThinkTags: (Response-side) Extracts inline <think>...</think> blocks from the content field and moves them to reasoning_content to align with DeepSeek-R1 behavior.

Manual overrides: If you encounter specific errors, you can manually toggle these (which are NOT included in the minimaxCompat preset):

• dropStreamOptions: Removes the stream_options field. Use this only if the upstream returns a 400 error, as it disables usage statistics in the admin dashboard.
• dropParallelToolCalls: Removes the parallel_tool_calls field.

The Session Manager allows you to browse and migrate Codex sessions across different providers.

Key features:

• View all sessions: The Session Manager tab reads the Codex state database (~/.codex/state_<N>.sqlite) to show sessions grouped by provider → project (cwd) → session, regardless of the currently active provider.
• Migration: You can migrate a session to a different provider. This rewrites the session's model_provider in the database and the rollout file's session_meta.
• Batch Migration: You can select multiple sessions via checkboxes and use "Migrate selected" to move them to a single provider at once.

Safety Mechanisms:

• Backups: Before any migration, mimo2codex snapshots the entire state database (including -wal and -shm files) and the rollout file into ~/.codex/.m2c-backups/sessions/<ts>/.
• Lock Protection: Migration will fail with a 409 codex_running error if Codex Desktop is currently running and holds a lock on the database. Ensure Codex is closed before migrating.

The desktop client performs passive update checks by comparing the local version against the latest GitHub Release tag.

Version Logic

• The check fetches the latest tag from the GitHub API.
• It uses parseDesktopVersion to extract [major, minor, patch] from tags like v0.5.0-desktop.
• An update is considered available via isMinorAhead if the latest version has a higher major version OR a higher minor version than the current version.

UI Integration

Instead of intrusive popups, the application uses setUpdateAvailable(true) to inject a ● Update available — Get latest item into the Tray menu, which links to the download page.

// Logic used to determine if a menu item should be shown
import { isMinorAhead, parseDesktopVersion } from './updateCheck.js';

const latest = parseDesktopVersion("v0.6.0-desktop"); // [0, 6, 0]
const current = parseDesktopVersion("v0.5.2-desktop"); // [0, 5, 2]

if (latest && current && isMinorAhead(current, latest)) {
  // Trigger tray menu update
}

The desktop application operates using a sidecar pattern. The Electron Main Process acts as a supervisor for a standalone mimo2codex-sidecar binary (compiled from the existing CLI via @yao-pkg/pkg).

Key Architectural Components:

• Electron Main Process: Manages the application lifecycle, tray/menu icon, settings window, logs window, and the sidecar process.
• Sidecar Manager: Uses child_process.spawn() to run the mimo2codex-sidecar binary. It monitors the process and handles automatic restarts (up to 1 retry) or displays error notifications if the sidecar fails to start.
• Data Isolation: The desktop version uses the OS userData directory (e.g., %APPDATA%\mimo2codex on Windows or ~/Library/Application Support/mimo2codex on macOS) to store .env, runtime.json, and logs. This ensures it remains physically isolated from the CLI version's ~/.mimo2codex/ directory.
• Port Management: Defaults to port 8788. If the port is occupied, the app automatically probes for the next available port and records it in userData/runtime.json.

This log message is not an error. It appears when you enable 'Thinking Mode' in a conversation where previous assistant messages do not contain reasoning_content (e.g., if you previously had thinking mode turned OFF or if the client didn't return reasoning items).

Providers like MiMo and DeepSeek V4 strictly require reasoning_content to be present in the entire conversation history when thinking mode is active. To prevent an upstream 400 Bad Request error, mimo2codex automatically injects a placeholder string "(this turn ran without thinking mode)" into those historical messages.

Key details:

• Functionality: Your current request will still use thinking mode.
• Impact: The placeholder makes the history compatible with the upstream API requirements without requiring you to start a new session.
• When to start a new session: If you feel the conversation history is too 'polluted' by these placeholders, starting a new session will clear the history and stop the injection.

[2026-05-20T02:42:14.123Z] INFO backfilled placeholder reasoning_content onto 1 historical assistant message(s) so thinking can stay ON for this request. These turns originally ran with thinking OFF (or the client didn't echo reasoning items). Placeholder text: "(this turn ran without thinking mode)".