{"id":45215906,"url":"https://github.com/avikalpa/codex-litellm","last_synced_at":"2026-04-13T10:02:16.524Z","repository":{"id":320928057,"uuid":"1083788613","full_name":"avikalpa/codex-litellm","owner":"avikalpa","description":"Maintained LiteLLM patchset for Codex CLI.","archived":false,"fork":false,"pushed_at":"2026-03-25T15:25:01.000Z","size":734,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T09:34:03.072Z","etag":null,"topics":["codex","codex-cli"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avikalpa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-26T18:04:58.000Z","updated_at":"2026-03-25T15:30:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"aed52cbc-ae77-47de-9221-0b690e3fba50","html_url":"https://github.com/avikalpa/codex-litellm","commit_stats":null,"previous_names":["avikalpa/codex-litellm"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/avikalpa/codex-litellm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avikalpa%2Fcodex-litellm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avikalpa%2Fcodex-litellm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avikalpa%2Fcodex-litellm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avikalpa%2Fcodex-litellm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avikalpa","download_url":"https://codeload.github.com/avikalpa/codex-litellm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avikalpa%2Fcodex-litellm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31747181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex","codex-cli"],"created_at":"2026-02-20T17:03:55.942Z","updated_at":"2026-04-13T10:02:16.518Z","avatar_url":"https://github.com/avikalpa.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# codex-litellm\n\nUse it with `npx`:\n\n```bash\nnpx @avikalpa/codex-litellm\n```\n\nOr install it globally:\n\n```bash\nnpm install -g @avikalpa/codex-litellm\n```\n\n`codex-litellm` is upstream Codex CLI with a maintained LiteLLM patchset.\n\nIt keeps the Codex agent loop, but lets you run it against agentic models from many providers through one LiteLLM gateway. The goal is to keep Codex usable over LiteLLM without asking users to learn a separate tool or maintain a long-lived fork.\n\n- Software license: Apache-2.0\n- Documentation license: CC BY 4.0\n- Current upstream base: `rust-v0.120.0`\n- Default LiteLLM runtime path: `/responses`\n\n## 1. What This Project Is For\n\nOfficial Codex is still the better choice when you want the official OpenAI-hosted harness, the cleanest flagship OpenAI path, and the least bridge complexity.\n\n`codex-litellm` is for a different job:\n- one Codex CLI talking to many providers through LiteLLM\n- agentic repository editing with non-OpenAI models\n- cost control and model experimentation without abandoning the Codex workflow\n- a patchset that stays close to upstream instead of turning into a separate product line\n\nThis project is strongest when you want Codex as the interface and LiteLLM as the routing layer.\n\n## 2. Install\n\nUse `npx` if you want the lightest possible start:\n\n```bash\nnpx @avikalpa/codex-litellm\n```\n\nUse a global install if you want the command available everywhere:\n\n```bash\nnpm install -g @avikalpa/codex-litellm\n```\n\nThis installs the command:\n\n```bash\ncodex-litellm\n```\n\nThe npm package downloads a prebuilt binary from GitHub Releases for your platform.\n\n## 3. First-Time Setup\n\n`codex-litellm` is meant to use the same default home as Codex: `~/.codex`.\n\nThat is intentional. The normal user path should not require a special debug-only `CODEX_HOME`.\n\nThe extra LiteLLM-specific inputs you usually need are:\n- `LITELLM_BASE_URL`\n- `LITELLM_API_KEY`\n\nPut them in `~/.codex/.env`:\n\n```bash\nmkdir -p ~/.codex\ncat \u003e ~/.codex/.env \u003c\u003c'EOF2'\nLITELLM_BASE_URL=http://localhost:4000/v1\nLITELLM_API_KEY=your-litellm-api-key\nEOF2\n```\n\nThen define the LiteLLM provider and a default profile in `~/.codex/config.toml`:\n\n```toml\n[model_providers.litellm]\nname = \"LiteLLM\"\nbase_url = \"http://localhost:4000/v1\"\nenv_key = \"LITELLM_API_KEY\"\nwire_api = \"responses\"\n\n[profiles.codex-litellm]\nmodel = \"vercel/minimax-m2.7-highspeed\"\nmodel_provider = \"litellm\"\n```\n\nFor most users, this is enough to get started.\n\n## 4. First Run\n\nStart the interactive CLI:\n\n```bash\ncodex-litellm\n```\n\nOr run a one-shot command:\n\n```bash\ncodex-litellm exec \"Summarize this repository\"\ncodex-litellm exec \"Refactor this function\" --model vercel/minimax-m2.7-highspeed\n```\n\nIf you already use plain `codex`, you can keep doing that. The two CLIs are meant to coexist.\n\n## 5. Shared Sessions\n\n`codex` and `codex-litellm` intentionally share the same session store under `~/.codex/sessions`.\n\nThat gives you one history, but two runtime defaults:\n- `codex` keeps the plain Codex provider and model defaults\n- `codex-litellm` keeps the LiteLLM provider and the `codex-litellm` profile defaults\n\nWhen you resume an old session from the other CLI, the active executable stays in charge of how the next turn is routed.\n\nPractical consequence:\n- resuming a plain Codex session from `codex-litellm` keeps LiteLLM active\n- resuming a LiteLLM session from `codex` keeps plain Codex active\n- the two CLIs should not clobber each other's remembered default model\n\nThis is intentional: one shared history, with separate runtime defaults for each CLI.\n\n## 6. Model Selection\n\nThe Codex harness rewards agentic behavior: models need to search, edit, stop at the right time, and return a final answer. A model that looks clever in benchmarks or chat demos may still be poor at Codex-style work.\n\nCurrent recommendation on the LiteLLM `/responses` path:\n- `Recommended default`: `vercel/minimax-m2.7-highspeed`\n- `Recommended cheaper second option`: `vercel/claude-haiku-4.5`\n- `Research lane`: `vercel/glm-5-turbo`, `vercel/gemini-3.1-pro-preview`, `vercel/grok-4.20-reasoning-beta`, `vercel/kimi-k2.5`\n- `Blocked`: `vercel/deepseek-v3.2-thinking`\n\nThe practical reading is simple:\n- start with MiniMax\n- if you want a cheaper serious option, try Claude Haiku\n- treat GLM, Gemini, Grok, and Kimi as research candidates, not default daily drivers\n- do not spend time trying to force DeepSeek through this `/responses` stack until the bridge issue is fixed\n\n### Why DeepSeek Is Marked Blocked\n\nDeepSeek is currently blocked because the LiteLLM `/responses` bridge is not carrying its tool-follow-up turns cleanly enough for reliable Codex use. This is a bridge-path issue, not just a model-quality issue.\n\n## 7. Economics\n\nThere is usually little value in routing an expensive flagship model through a weak bridge path.\n\nIf your real goal is the best possible flagship OpenAI Codex experience, the official harness is usually better value:\n- fewer moving parts\n- fewer provider quirks\n- less time burned debugging the transport instead of doing work\n\n`codex-litellm` is strongest when you want:\n- model choice\n- pricing flexibility\n- multi-provider experimentation\n- good agentic behavior from non-OpenAI routes\n\nPractical spending advice:\n- if you want the safest default here, spend on MiniMax first\n- if you want a cheaper serious lane, try Claude Haiku before escalating to more expensive research models\n- treat GLM, Gemini, Grok, and Kimi as measured experiments, not daily-driver defaults\n- do not spend money re-proving DeepSeek on the current `/responses` stack until the bridge issue is fixed\n- if you are mainly chasing flagship-quality output rather than multi-provider flexibility, use official Codex instead of paying an indirection tax here\n\nUse the route that gives you the best result for the money and operational complexity.\n\n## 8. Semantic Cache\n\nIf your LiteLLM deployment supports semantic cache, use it.\n\nThe practical pattern is:\n- keep the expensive reasoning model for actual turns\n- use a cheap embedding route for cache lookup\n\nA good shape is:\n- `vercel/gemini-embedding-001`\n\nWhy this matters:\n- cache probes become almost zero-cost relative to a full agentic turn\n- repeated repo-edit loops cost less\n- you get the benefit at the LiteLLM layer without adding more cache logic inside `codex-litellm`\n\n## 9. `/responses` Is The Supported Path\n\n`codex-litellm` now treats LiteLLM `/responses` as the default forward path.\n\nThat means:\n- new work is validated against `/responses`\n- model curation is based on `/responses` behavior\n- known-broken routes are documented plainly instead of hidden behind fallback folklore\n\nA route should only be treated as supported if it works on the path users are expected to run.\n\n## 10. How We Judge Models\n\nThese ratings come from live `codex-litellm` runs through the Codex harness, not benchmark claims, API checks, or chat impressions.\n\nA model is only useful here if it can:\n- inspect a real repository\n- use tools correctly\n- make a real repo diff\n- stop after the edit instead of looping forever\n- return a final assistant answer\n\nGood benchmark scores are not enough.\n\n### Benchmarks vs Reality\n\nWe do look at benchmark data, especially Artificial Analysis, but only as an intake signal.\n\nBenchmarks are useful for:\n- deciding which newly available models are worth paying to probe\n- spotting which providers are moving quickly on agentic behavior\n- avoiding obviously stale or weak candidates\n\nBenchmarks are not enough for:\n- proving tool-use quality\n- proving stop/finalize discipline after an edit\n- proving the LiteLLM `/responses` bridge is stable for that route\n- proving the model is worth its price on real repository work\n\nBenchmark rank can earn a model a place on the research bench, but only live repo-edit runs can earn it a recommendation.\n\n### Current Results\n\nIf you just want the short version:\n- use MiniMax first\n- use Claude Haiku when you want the cheaper serious option\n- treat GLM, Gemini, Grok, and Kimi as research lanes\n- treat DeepSeek as blocked on the current `/responses` stack\n\nThe table below summarizes current live results.\n\n| Model | `mini-web` | `python-cli` | `calibre-web` exploratory | What usually goes wrong | Current recommendation |\n| --- | --- | --- | --- | --- | --- |\n| `vercel/minimax-m2.7-highspeed` | PASS | PASS | FAIL under route pressure, no clean diff on the latest heavy probe | larger repos currently amplify retry or 429 noise | recommended default |\n| `vercel/claude-haiku-4.5` | PASS | PASS | not yet cleanly completed in the latest heavy probe batch | needs more large-repo evidence | recommended cheaper second option |\n| `vercel/glm-5-turbo` | FAIL | FAIL | FAIL | retry and 429 noise before a useful diff | research lane only |\n| `vercel/gemini-3.1-pro-preview` | EDITS, THEN STALLS | TIMEOUT | blocked by current gateway credits on the latest heavy probe | post-edit finalization is still too weak, and heavy-repo results are currently confounded by billing state | watchlist only |\n| `vercel/grok-4.20-reasoning-beta` | PASS | FAIL | incomplete probe | can look strong on light UI work, then fail to produce a qualifying diff on procedural work | watchlist only |\n| `vercel/kimi-k2.5` | FAIL | PASS | blocked by current gateway credits on the latest heavy probe | behavior is fixture-sensitive; it handles procedural edits better than broad UI hunting | research lane only |\n| `vercel/deepseek-v3.2-thinking` | BLOCKED | BLOCKED | not worth probing further until bridge fix | LiteLLM `/responses` tool-follow-up incompatibility | blocked on this stack |\n\n### What The Labels Mean\n\n- `PASS` means the model completed a Codex-harness run with a real repo diff and a final answer.\n- `EDITS, THEN STALLS` means the model found the right change, but did not exit cleanly enough to be trustworthy.\n- `FAIL` means it either never produced the required diff or collapsed into retries, rate limits, or a no-op finish.\n- `BLOCKED` means the problem is below normal model quality. The current bridge path is incompatible.\n\n## 11. Research Bench\n\nThe repository includes a public smoke bench that:\n- resolves live model IDs from your LiteLLM `/v1/models`\n- sanitizes private route segments before writing public output\n- runs real Codex-harness repo-edit tasks, not toy prompt checks\n- refuses to call a run a pass unless it produces a non-empty repo diff\n\nThe active fixtures are intentionally different:\n- `mini-web` checks whether a model can inspect, edit, and finalize a concrete UI restyle\n- `python-cli` requires diffs in the CLI file, the README, and the test file, so partial edits do not count as a pass\n- `calibre-web` is the heavier real-world probe for large-repo search, edit discipline, and route stability\n\nThis bench helps us:\n- separate “sounds smart” from “can finish Codex work”\n- measure whether a model is worth its route cost\n- catch regressions in the LiteLLM bridge before users do\n- build evidence strong enough to block or allow release lanes\n\nCurrent takeaways:\n- MiniMax is still the best overall default on this stack because it clears the harness often enough to justify its cost.\n- Claude Haiku is the best cheaper second option so far.\n- Kimi, GLM, Gemini, and Grok have shown promise, but they are still bench-dependent rather than operationally stable.\n- DeepSeek remains blocked by the current `/responses` bridge, so more paid probing there has low return.\n- Heavier repos matter; some models that look fine on `mini-web` degrade sharply when the task shifts to larger search spaces and stricter edit discipline.\n\nIf you care about benchmark-style content, the project’s position is:\n- we use benchmarks to choose what to test\n- we use Codex-harness repo-edit runs to decide what to recommend\n- we use cost and completion quality together, not benchmark rank alone\n\nRun the public bench with:\n\n```bash\nscripts/run-public-smoke-bench.sh --profile ~/.codex\n```\n\n## 12. Troubleshooting\n\nIf a model behaves badly:\n1. Confirm your LiteLLM gateway is reachable.\n2. Confirm the route exists on `/v1/models`.\n3. Retry with MiniMax before blaming the patchset.\n4. Run `scripts/run-public-smoke-bench.sh --profile ~/.codex`.\n\nIf install fails:\n1. Verify GitHub Releases is reachable.\n2. Re-run `npm install -g @avikalpa/codex-litellm`.\n3. If your platform is unsupported, build from source.\n\nCommon mistakes:\n- starting with non-agentic models\n- assuming `/v1/models` availability means Codex-harness readiness\n- reading benchmark rank as proof of tool-use quality\n- spending premium-model money through a route that is already known to be weak\n\n## 13. Build From Source\n\nFor local testing, do not use `build.sh`. That is release automation and resets the upstream checkout.\n\nFastest local debug build:\n\n```bash\n./scripts/build-local-fast.sh\n```\n\nRun it from the repo root with the launcher:\n\n```bash\n./codex-litellm\n```\n\nOr run the binary directly from the upstream workspace target dir:\n\n```bash\n./codex/codex-rs/target/debug/codex-litellm\n```\n\nNotes:\n- `./target/debug/codex-litellm` from the repo root is the wrong path\n- `../codex/codex-rs/target/debug/codex-litellm` is the wrong path from this repo; that points outside this checkout\n- the helper enables incremental builds and uses `sccache` automatically if it is installed\n- keep `codex/codex-rs/target/` around between builds; that is where most of the speedup comes from\n\n## 14. For Developers\n\nUser-facing docs live in `README.md`.\n\nOperator-facing docs live in:\n- `AGENTS.md`\n- `agent_docs/`\n\nIf user-facing behavior changes, update `README.md` and the changelog to match.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favikalpa%2Fcodex-litellm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favikalpa%2Fcodex-litellm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favikalpa%2Fcodex-litellm/lists"}