English · Simplified Chinese
Codex Switch manages AI providers, agents, chat, drawing, sessions, MCP, Skills, vision fallback, and web search on Windows.
The app writes the native config files those agents already use, while a local compatibility proxy on 127.0.0.1:47632 fills the protocol gaps when a provider does not match the target runtime. That is how chat-completion providers such as DeepSeek, MiMo, and GLM can be used from Codex-style workflows, how text-only models can receive image descriptions from a configured vision model, and how models without native web search can call local web__search and web__fetch tools.
All provider records and capability metadata stay on the machine in local storage. API keys are not sent to a hosted Codex Switch service.
- API Providers: manage OpenAI, OpenAI Compatible / New API, Anthropic Compatible, Gemini, Ollama, OpenRouter, Hugging Face, DeepSeek, MiMo, GLM, and other records.
- Agents: generate and switch Codex, Claude Code, and Gemini runtime configs from saved provider records.
- Talking: chat with text, files, and images when the selected model supports them.
- Drawing: generate and edit images with supported OpenAI-compatible image endpoints.
- Sessions: inspect local sessions, preview transcripts, copy resume commands, generate handoff text, and repair hidden Codex sessions.
- Vision fallback: let text-only models such as DeepSeek, MiMo, and GLM understand image input through a configured vision model.
- Automatic web search: add local
web__searchandweb__fetchtools for models or providers, such as DeepSeek, MiMo, and GLM, that do not have native web search. - Capabilities: discover, test, install, and sync MCP servers and Skills across Codex, Claude Code, and Gemini.
- Settings: configure directories, terminal, language, theme, background, release access, vision fallback, and web search.
| Providers | Agents |
|---|---|
 |
 |
| Manage provider records, keys, base URLs, model discovery, and provider websites. | Generate Codex, Claude Code, and Gemini profiles from saved providers. |
| Talking | Drawing |
 |
 |
| Chat with models using text, files, images, and automatic tool support. | Generate and edit images with compatible image models. |
| Sessions | Settings |
 |
 |
| Browse local transcripts, copy resume or handoff commands, and restore hidden Codex sessions with Repair Visibility. | Configure app paths, appearance, updates, vision fallback, and web search. |
| Vision Fallback | Web Search |
|---|---|
 |
 |
| Route image understanding through a configured vision provider for text-only models. | Configure search and fetch providers for model-driven web access. |
| MCP Servers | Skills |
 |
 |
| Discover, test, install, and sync MCP servers across supported agents. | Discover, review, install, and sync Skills across supported agents. |
| CLI Vision Input | CLI Vision Output |
|---|---|
 |
 |
| Send image context from the CLI through the local vision fallback pipeline. | Text-only models receive structured image descriptions before answering. |
| CLI Web Search Request | CLI Web Search Result |
 |
 |
| Models without native web search can call local `web__search` and `web__fetch` tools. | The compatibility proxy returns source context to the model for the final answer. |
| Modes | Themes |
|---|---|
 |
 |
React feature pages
Providers / Agents / Talking / Drawing / Capabilities / Settings
|
v
src/api/tauri.ts appApi
|
v
Tauri invoke(...)
|
v
src-tauri/src/commands.rs
|
+--> database.rs -> local SQLite app state
+--> agent_writer.rs -> Codex / Claude / Gemini config files
+--> compatibility_proxy.rs -> runtime bridge on 127.0.0.1:47632
+--> capabilities.rs -> MCP + Skill discovery, testing, sync
+--> provider APIs -> chat, model list, image generation, OAuth
The frontend keeps pages and form state in React. src/api/tauri.ts is the only bridge to Rust commands, so new contributors can follow a feature by starting at its page, finding the matching appApi method, and then reading the Tauri command implementation.
ProvidersPage.tsx
|
v
appApi.saveApiProvider / listProviderModels / startOpenAiOauth
|
v
commands.rs
|
+--> database.save_api_provider -> reusable local record
+--> remote model list / OAuth -> optional provider metadata
+--> active linked Agent refresh -> agent_writer when auth changes
Provider records are reusable API connection profiles. The frontend owns provider editing, model discovery, OAuth entry points, website links, and local form state. The backend stores providers in the local SQLite database and keeps API keys on the local machine. Provider presets and normalization keep OpenAI-compatible, Anthropic-compatible, Gemini, Ollama, OpenRouter, Hugging Face, and other providers under one UI model.
AgentsPage.tsx
|
v
appApi.saveProvider / activateProvider
|
v
commands.rs -> database.save_provider / activate_provider
|
v
agent_writer::write_provider
|
+--> Codex -> ~/.codex/config.toml + ~/.codex/auth.json
+--> Claude -> ~/.claude/settings.json
+--> Gemini -> ~/.gemini/settings.json + ~/.gemini/.env
|
v
tray refresh + current runtime profile
Agent profiles bind a saved provider to a runtime target: Codex, Claude Code, or Gemini. When a profile is activated, Codex Switch writes the target tool's config using the selected provider, model, base URL, reasoning options, and extra config fields. If a non-native provider needs protocol translation or fallback capabilities, the generated config points the agent to the local proxy path for that runtime.
TalkingPage.tsx
|
v
appApi.sendChatMessage
|
v
commands::send_chat_message
|
+--> optional vision_fallback::preprocess_chat_messages
|
v
send_chat_message_blocking
|
+--> Anthropic-compatible -> /messages
+--> Gemini -> :generateContent
+--> OpenAI-compatible -> /chat/completions
+--> OpenAI-compatible + configured web search
-> web__search / web__fetch loop, max 8 tool steps
Talking sends messages through the selected provider and model, preserving files and image attachments when the model supports them. For text-only models with vision fallback enabled, image attachments are first converted into text descriptions by the configured vision provider. When an OpenAI-compatible model or provider does not have native web search, such as DeepSeek, MiMo, or GLM, Codex Switch can run local web__search and web__fetch tool calls before returning the final answer.
DrawingPage.tsx
|
v
appApi.generateImage
|
v
commands::generate_image
|
+--> prompt only -> /images/generations JSON
+--> prompt + input image -> /images/edits multipart
|
v
extract_images -> persist_generated_images
|
v
local drawing image files + Drawing record rail
Drawing focuses on OpenAI-compatible image endpoints. Anthropic-compatible and Gemini providers are rejected in this page because their image generation routes are not wired here. The feature keeps prompt state, provider/model selection, generation/edit requests, local records, saved image paths, and image zoom behavior inside the Drawing feature boundary.
SessionsPage.tsx
|
v
appApi.getCachedSessions / refreshSessions / repairCodexSessionVisibility
|
v
commands.rs -> database.rs -> session_manager.rs
|
+--> cached sessions -> fast first page load
+--> manual refresh -> rescan Codex / Claude / Gemini session files
+--> Repair Visibility -> read Codex sessions, update Codex state/index records,
then refresh only Codex Switch's Codex session cache
Sessions are indexed locally so the page can open quickly without rescanning every transcript on startup. Manual refresh still performs a full local session scan when the user asks for it. Repair Visibility is for Codex sessions that still exist on disk but do not appear in Codex's session list. It reads the configured Codex session files, repairs the Codex state/index records needed for visibility, and then updates Codex Switch's cached Codex sessions without rebuilding all agent session data.
Codex / Claude Code / Gemini CLI
|
v
generated config points to local gateway when needed
|
v
127.0.0.1:47632
|
v
compatibility_proxy::handle_connection
|
+--> /v1/models -> synthetic current model list
+--> /v1/responses -> native Responses API or relay_translate to Chat
+--> /anthropic/... -> Anthropic-compatible gateway
+--> /gemini/... -> Gemini-compatible gateway
|
v
vision_fallback and local web tools are applied before upstream calls when enabled
Codex Switch starts a local in-process proxy on 127.0.0.1:47632. Each request is matched to the current provider for the target agent. Codex /v1/responses requests either pass through to a Responses-capable provider or use relay_translate to call /chat/completions and translate the result back. Claude and Gemini gateway paths let those CLIs use the same configured provider and fallback logic.
Codex CLI /v1/responses request
|
v
compatibility_proxy::handle_chat_completions_provider
|
+--> optional vision_fallback::preprocess_codex_body
|
v
relay_translate::translate_request
|
+--> normalize Responses input -> chat messages
+--> preserve request metadata: tools, tool_choice, temperature, top_p
+--> convert developer messages -> system messages
+--> transform tools for /chat/completions
|
+--> local_shell -> function shell_command
+--> custom/tool_search -> function tools
+--> namespace -> nested function tools
+--> provider web_search when supported by upstream
+--> drop proxy-hosted, server-side-only, or unknown tools
+--> apply provider quirks for DeepSeek, MiMo, and GLM
|
v
POST provider /chat/completions
|
v
relay_translate::translate_sync_response or handle_chunk
|
+--> assistant text -> Responses message item
+--> reasoning_content -> Responses reasoning item
+--> tool_calls -> response.function_call events
+--> shell call aliases -> shell_command schema for Codex
|
v
Codex receives Responses-shaped JSON or SSE
The relay is a protocol bridge, not a tool runner. Codex client tools such as shell_command, apply_patch, and MCP tools are translated into chat-completion function calls for the upstream model, then translated back into Responses function-call events so Codex can execute them. The proxy only executes proxy-hosted fallback tools, such as local web search.
settings + provider model metadata
|
v
vision_fallback::model_vision_capability
|
+--> Vision or Unknown -> keep original image request
|
+--> TextOnly + enabled toggle
|
v
preprocess_chat_messages / preprocess_codex_body
preprocess_anthropic_body / preprocess_gemini_body
|
v
describe_image with configured vision provider, max 6 images, cached descriptions
|
v
replace image parts with <vision-analysis> text before main model call
Vision fallback is used only when the main model is detected as text-only and the corresponding Talking, Codex, Claude, or Gemini toggle is enabled. This lets text-only models such as DeepSeek, MiMo, and GLM understand images through a configured vision model. Descriptions are cached by image and prompt to avoid repeated vision calls.
model without native web search
|
v
web__search / web__fetch tool call
|
v
commands.rs or compatibility_proxy.rs
|
v
web_search.rs
|
+--> search providers: Tavily / Zhipu / Exa / Bocha / SearXNG / Jina
+--> fetch providers: direct fetcher / Jina Reader
|
v
numbered source JSON returned to the model for final answer
Automatic web search is configured once in Settings for models or providers that need local web access, such as DeepSeek, MiMo, or GLM. Supported search providers include Tavily, Zhipu, Exa, Bocha, SearXNG, and Jina. Fetching can use the built-in direct fetcher or Jina Reader. Direct fetching validates redirects, blocks private and reserved network addresses, accepts readable text formats only, and limits responses to 10 MB.
Codex /v1/responses request
|
v
relay_translate::translate_request -> /chat/completions body
|
v
should_enable_local_web
|
+--> Settings web search enabled
+--> search provider configured
|
v
prepare_local_web_agent_body
|
+--> force stream=false for the upstream web loop
+--> set parallel_tool_calls=false
+--> remove provider-native web_search tool shapes
+--> inject web__search and web__fetch function tools
|
v
run_local_web_agent, max 8 steps
|
+--> POST provider /chat/completions
+--> no tool_calls
| |
| v
| final assistant answer
|
+--> web__search call
| |
| v
| web_search::search_keywords -> numbered source JSON
|
+--> web__fetch call
|
v
web_search::fetch_urls -> numbered source JSON
|
v
append assistant tool_call + tool result messages, then repeat
|
v
relay_translate::translate_sync_response
|
v
Codex receives final Responses JSON or synthetic Responses SSE
Only web__search and web__fetch are consumed inside this loop. If the model asks for normal Codex tools such as shell_command, the proxy returns those tool calls to Codex instead of trying to run them itself. This keeps local web search separate from Codex's normal tool execution path.
CapabilitiesPage.tsx
|
v
appApi.getCapabilitiesState / saveMcpServer / testMcpServer / syncMcpCapabilities
|
v
commands.rs -> capabilities.rs
|
+--> discover Codex config.toml, Claude .claude.json, Gemini settings.json
+--> save to SQLite, redact secret values in UI, secure secrets with keyring
+--> test stdio / HTTP / SSE server definitions
+--> sync_mcp_agent writes target agent config format
The Capabilities page discovers MCP servers from Codex, Claude Code, and Gemini config files. Servers can be stored, tested, assigned to target agents, and synced back to the target config format. Secret values are redacted in the UI and stored through the operating system keychain where needed.
CapabilitiesPage.tsx
|
v
appApi.importSkill / saveSkill / searchMarketplace / installMarketplaceSkill
|
v
commands.rs -> capabilities.rs / marketplace.rs
|
+--> discover SKILL.md roots in Codex, Claude, Gemini, and ~/.agents/skills
+--> write app-managed or external SKILL.md files
+--> hide built-in system skills from normal management
+--> sync_skill_agent mirrors selected skills to target agents
Codex Switch discovers local Skills from Codex, Claude Code, Gemini, and shared agent skill roots. Built-in system skills are hidden from normal management, while external skills can be reviewed and synced across targets. Marketplace installs remain pinned until the user explicitly updates them.
Download the latest Windows release:
https://github.com/baosen-h/codex-switch/releases/latest
npm install
npm run build
npm run tauri -- build- Frontend architecture and contribution rules: docs/frontend-architecture.md
- Feature ownership rules: src/features/README.md
- Windows-first.
- API keys are stored locally.
- Drawing is focused on OpenAI-compatible image endpoints.
- Vision fallback only lists models verified to accept image input and return text.
- Found a problem? Submit an Issue.
- Contributions are welcome. Open a Pull Request to help improve the project.
MIT. See LICENSE.