codex-deepseek-shim

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

codex-deepseek-shim

(★ 9)

Provider shim + model router + subagent task relay for DeepSeek and cross-provider subagents in the stock Codex desktop app

codex-deepseek-shim Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# codex-deepseek-shim

**Keep the native Codex Desktop workflow. Add provider choice.**

`codex-deepseek-shim` is a local compatibility router that lets Codex Desktop
use OpenAI, DeepSeek, and configured local Ollama models without patching the
app bundle or replacing Codex's app-server lifecycle.

Current router contract: **v2.0.0**.

Codex continues to see its built-in `openai` provider and native Responses
contract. The router selects the physical upstream from the model on each
request and adapts only the provider-specific boundary before returning native
Responses-compatible state to Codex.

```text
Codex Desktop
    |
    v
shim.js -> Codex app-server -> provider-router.mjs
                              |-- deepseek-*   -> DeepSeek API
                              |-- ollama/*     -> local Ollama
                              `-- gpt-/codex-* -> ChatGPT backend
```

## Why use it

- **One durable task, multiple providers.** Switch GPT/Codex → DeepSeek →
  configured Ollama → GPT/Codex inside the same task while preserving the
  conversation and durable task identity.
- **Native Codex continuity.** The durable provider remains `openai`, so task
  IDs, sidebar and Remote listing, history replay, app lifecycle, and usage
  attribution stay on the Codex path.
- **Native capabilities stay native.** Codex remains responsible for model
  selection, tools, history, images and modality filtering, and compaction.
  The router does not become a second task or history authority.
- **OpenAI remains pass-through.** OpenAI Responses requests and responses stay
  semantically transparent. DeepSeek and Ollama adapters are additive and
  limited to demonstrated provider differences.
- **Focused integration surface.** The project is an external, inspectable
  Node.js layer; it does not modify the Codex Desktop app bundle.
- **Automatic recovery for oversized compaction.** A compatible registered
  model can privately recover an exact native context-limit failure without
  changing the task's provider or history; otherwise the original failure is
  preserved. See the
  [engineering contract](docs/ENGINEERING.md#automatic-whole-request-compaction-recovery).

## Independent projects, shared direction

This router and [OpenCodex](https://github.com/lidge-jun/opencodex) are
independent, unaffiliated projects that share a belief in expanding provider
choice. OpenCodex is a sister in spirit, not an official partner, dependency,
or endorsed integration.

Use this router for a workflow centered on native Codex Desktop and app-server
continuity. OpenCodex serves its own client-centered workflows. Users may
choose either or use both. Neither project is a fallback for, replacement for,
competitor to, or universally better version of the other.

## Quick start

Prerequisites: macOS, Codex Desktop, Node.js 22 or newer, and a DeepSeek API
key.

1. Put the launcher files in one directory and install the pinned runtime
   dependency:

```sh
   npm ci --omit=dev --ignore-scripts
   ```

The exact launcher file list and lifecycle requirements are in
   [Installation and deployment](docs/ENGINEERING.md#installation-and-deployment).

2. Keep the task's durable provider as `openai` and point the supported
   inference base URL at the loopback router:

```toml
   model = "deepseek-v4-flash"
   model_provider = "openai"
   openai_base_url = "http://127.0.0.1:17899/"
   ```

3. Store the DeepSeek key outside the repository:

```sh
   mkdir -p ~/.codex/secrets
   chmod 700 ~/.codex/secrets
   printf 'DEEPSEEK_API_KEY=%s\n' '<your-key>' > ~/.codex/secrets/deepseek.env
   chmod 600 ~/.codex/secrets/deepseek.env
   ```

4. Launch Codex Desktop through the shim:

```sh
   launchctl setenv CODEX_CLI_PATH "<launcher-dir>/tools/codex-provider-shim.sh"
   ```

`CODEX_CLI_PATH` is a Desktop process environment setting, not a Codex
   `config.toml` key.

5. Verify the installation, quit Codex Desktop completely, and reopen it:

```sh
   node shim.js --shim-selftest
   node capability-contract-test.mjs
   node dynamic-reasoning-test.mjs
   node realtime-router-test.mjs
   bash verify-after-update.sh
   ```

Then choose models through Codex's native model-setting path. The included
profile recognizes OpenAI-family and DeepSeek-family models; optional local
Ollama aliases require their explicit profile and runtime setup.

Existing beta tasks that were persisted under a transport provider can use the
bounded [provider-state repair workflow](fix_provider_state/README.md).

## Current proof and limits

The repository contains deterministic coverage for routing, Responses
adaptation, tool round-trips, provider lifecycle bounds, capability
registration, secret egress controls, and recovery contracts. Documented
Codex Desktop runs have observed provider switching and heterogeneous
delegation; the detailed evidence and status labels are in the
[engineering reference](docs/ENGINEERING.md).

Important limits:

- DeepSeek and current Ollama adapters accept text input only.
- Native image input on the OpenAI forwarding alias remains **Unverified**;
  no current alias advertises vision.
- Requested model roles do not prove the model actually served. Served model
  identity remains **Unverified** without authoritative runtime attestation.
- Real Ollama execution, hardware behavior, and compatibility across model
  revisions remain **Unverified** until exercised on the target installation.
- Source tests and installation checks do not prove that a running Codex
  Desktop process has reloaded the code. Restart and live task acceptance are
  separate evidence.

## Documentation

- [Engineering reference](docs/ENGINEERING.md): architecture, invariants,
  provider adapters, wire behavior, secret redaction, recovery, tests,
  deployment, and troubleshooting.
- [Router and shim design gate](docs/DESIGN_GATE.md): the compatibility
  contract every transport or provider change must preserve.
- [Provider-state repair](fix_provider_state/README.md): bounded repair for
  beta tasks persisted under a transport provider.

codex-deepseek-shim

codex-deepseek-shim Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

codex-deepseek-shim

codex-deepseek-shim Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README