feat(cli): per-agent lite claude / codex / opencode commands that wrap coding agents through the proxy

[mateo-berri]

Relevant issues

Linear ticket

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

CI (LiteLLM team)

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Screenshots / Proof of Fix

https://www.loom.com/share/d250e489092a44a9872eeae805253125

Runbook a user follows. Start a proxy that exposes the model the agent will request, then launch the agent through its command:

# 1. start the proxy with a config that maps the model names your agent requests
python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload --use_v2_migration_resolver 2>&1 | tee litellm.log

# 2. authenticate the CLI against the proxy (browser SSO), or set LITELLM_PROXY_API_KEY for non-interactive use
lite login

# 3. launch an agent; all its LLM traffic now flows through the proxy
lite claude
lite codex
lite opencode

Anything after the agent name is forwarded to it, e.g. lite claude --resume or lite codex exec "summarize the repo". Whatever the agent sends lands on the proxy's /v1/messages (Claude Code) or /v1/chat/completions and /v1/responses (Codex, OpenCode), so it shows up in the logs at http://localhost:4000/ui/?page=logs and bills against the proxy.

To show the per-agent env wiring without a real agent install, I put fake claude and codex binaries on PATH that print what they received (run with --skip-verify so no proxy is needed). Note the trailing-slash base URL is normalized, the forwarded args arrive verbatim, and a pre-existing ANTHROPIC_API_KEY is dropped for Claude Code:

$ lite --api-key sk-litellm-demo --base-url http://localhost:4000/ claude --skip-verify --resume -p hi
litellm: routing Claude Code through proxy at http://localhost:4000
argv: --resume -p hi
ANTHROPIC_BASE_URL=http://localhost:4000
ANTHROPIC_AUTH_TOKEN_set=yes
ANTHROPIC_API_KEY_set=no

$ lite --api-key sk-litellm-demo --base-url http://localhost:4000/ codex --skip-verify exec "do a thing"
litellm: routing Codex through proxy at http://localhost:4000
argv: exec do a thing
OPENAI_BASE_URL=http://localhost:4000/v1
OPENAI_API_KEY_set=yes

Claude Code gets the Anthropic env with the bare proxy root (it appends /v1/messages); Codex gets the OpenAI env with the /v1 suffix; the wrapper then execs the agent so the TTY and signals pass through

Type

🆕 New Feature

Changes

Each supported coding agent is now its own top-level command, so launching one is lite claude, lite codex, or lite opencode, with everything after the agent name forwarded straight to it. This replaces the earlier run -- form and the claude-code shortcut; the aim was the least typing and nothing to remember beyond the agent's own name. The commands are generated from a single registry, so adding an agent is one entry.

The console script also gains a shorter name: lite is added as the recommended entry point, so the whole surface becomes lite claude, lite codex, lite login, and so on. The existing litellm-proxy script stays as an alias for the same CLI, so anything that hard-codes litellm-proxy in scripts or CI keeps working; both names map to the same command

The DX follows the agent-vault pattern: automatic SSO login when at a terminal, an env-key "agent mode" for containers and CI (set LITELLM_PROXY_API_KEY and it won't try to open a browser), and a fail-fast preflight that checks the key against the proxy so bad or expired credentials surface immediately with a clear message instead of failing deep inside the agent.

Variables are chosen per agent. Claude Code receives ANTHROPIC_BASE_URL set to the bare proxy root (Claude Code appends /v1/messages) and ANTHROPIC_AUTH_TOKEN, with any stray ANTHROPIC_API_KEY removed so the proxy token always wins. Codex and OpenCode receive OPENAI_BASE_URL set to the proxy plus /v1 and OPENAI_API_KEY. On success the wrapper execs the agent, replacing itself so the TTY and signals pass through cleanly. A first launch that still has to authenticate does the SSO login in the same process and then execs the agent. Completing the browser login can leave stdin no longer attached to the terminal, so a TUI agent like Claude Code would start in non-interactive --print mode and exit immediately with "Input must be provided ...". The wrapper now reopens the controlling terminal onto stdin just before handoff when the session started interactively, so the very first lite claude drops you straight into the agent with no second run; piped or redirected input is detected up front and left alone, so non-interactive and agent-mode use still behave as before

While documenting the lite login flow I also fixed the CLI SSO success page, which got stuck showing "Closing..." forever. The CLI opens that page with webbrowser.open, so the browser tab is not script-opened and the browser refuses window.close(); the old 3-2-1 countdown therefore ended on "Closing..." and the tab sat there indefinitely. The page now drops the countdown and shows "You can now close this window and return to your terminal." from the start, while still attempting window.close() once so the tab still auto-closes in the rare case the browser allows it

The one-line installer (scripts/install.sh, run via curl -fsSL https://raw.githubusercontent.com/BerriAI/litellm/main/scripts/install.sh | sh) needs only curl: it bootstraps uv when missing and installs with --python-preference system, so uv reuses a compatible system Python when there is one and downloads a managed build otherwise. Because uv reads litellm's requires-python instead of the script guessing with a floor-only check, a system Python outside the supported range (a too-old 3.9 or a too-new 3.14) is skipped rather than force-fed to uv tool install and failing to resolve

Laptop users who only want the lite client now have a thin install that skips the proxy server entirely. The CLI's heavy imports (fastapi, cryptography, and the rest of the server tree) are all guarded, so a new litellm[cli] extra carrying just rich, pyyaml and requests is enough to run lite login and lite claude. scripts/install-cli.sh (curl -fsSL https://raw.githubusercontent.com/BerriAI/litellm/main/scripts/install-cli.sh | sh) installs that extra the same way install.sh does, with --python-preference system, so uv reuses a compatible system Python or downloads a managed one and sidesteps both a too-old 3.9 and a too-new 3.14 system Python. A BerriAI/homebrew-litellm tap formula is included under packaging/homebrew/ for a brew install path; it activates with the first release that ships the cli extra, following the runbook there. A pyproject thin-contract test fails if the cli extra loses a dep the CLI imports or gains a server-only one, so the laptop install cannot silently re-bloat

To pin a model, pass the agent's own model flag (for example lite claude --model my-proxy-model) or export the variable the agent reads (ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODEL for Claude Code); the wrapper preserves what you already have set, so there is no separate --model flag to intercept what the agent owns.

The logic is split into dependency-injected helpers (agent_profile, build_agent_env, verify_proxy_key, run_agent) so the env wiring, preflight, and launch handoff are unit-tested without monkeypatching, plus CliRunner tests for argument forwarding, auth resolution, agent mode, and auto-login. I mutation-tested the env profiles, the /v1 suffix, the preflight, and the binary-plus-args forwarding to confirm the tests fail when the behavior is broken.

This supersedes #29846, which was opened from a claude/-prefixed branch and only covered Claude Code; that PR has been closed in favor of this one

[codecov]

Codecov Report

❌ Patch coverage is 87.90323% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/client/cli/commands/agents.py	90.51%	11 Missing ⚠️
litellm/proxy/client/cli/interface.py	0.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds per-agent lite claude, lite codex, and lite opencode top-level commands that route each coding agent's LLM traffic through a LiteLLM proxy, plus a thin litellm[cli] install extra and companion scripts/install-cli.sh for laptop users who don't need the full proxy server.

• agents.py: A single registry drives all three commands; build_agent_env handles per-agent env var wiring (Anthropic bare root vs OpenAI /v1 suffix, ANTHROPIC_API_KEY removal), _codex_proxy_args injects the necessary -c provider overrides since Codex ignores OPENAI_BASE_URL, and _restore_controlling_terminal reopens /dev/tty onto stdin so an interactive session that went through SSO doesn't hand off to a TUI agent in non-interactive mode.
• SSO success page: Replaces the stalled "Closing…" countdown with a static manual-close message and an immediate (likely no-op) window.close() call; the litellm-proxy console-script alias is preserved alongside the new lite entry point.
• Test coverage: DI-injected unit tests cover env profiles, Codex override args, preflight verification, skip-verify, binary-not-found hints, terminal reattachment ordering, and all interactive/non-interactive auth paths via CliRunner; a pyproject contract test prevents the thin cli extra from silently re-gaining server-only deps.

Confidence Score: 5/5

Safe to merge — all changes are additive CLI plumbing with no impact on the proxy request path.

The change is entirely additive: new CLI commands, a new pyproject extra, new install scripts, and a cosmetic SSO page fix. None of the changed code touches the proxy's request handling, authentication middleware, or any shared runtime path. The agent wiring is isolated to the lite CLI client, tested end-to-end with DI stubs, and the litellm-proxy alias is preserved for backward compatibility.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/client/cli/commands/agents.py	New file: agent registry, env-profile builder, Codex -c args generator, preflight verifier, and exec handoff — all DI-injected and cleanly tested.
litellm/proxy/client/cli/main.py	Adds import of agent_commands and registers one top-level CLI command per known agent; straightforward loop over the registry.
pyproject.toml	Adds cli thin-client extra (rich, pyyaml, requests); adds lite console script while keeping the litellm-proxy alias intact.
litellm/proxy/common_utils/html_forms/cli_sso_success.py	Replaces the "closing in 3 seconds" countdown (which stalled on "Closing…") with a static "close this window" message and an immediate window.close() attempt.
scripts/install-cli.sh	New thin-client installer: bootstraps uv if needed, installs litellm[cli] with --python-preference system, and guides users to lite login.
scripts/install.sh	Drops the manual Python version check in favor of letting uv honor requires-python, switching from --python PYTHON_BIN to --python-preference system.
tests/test_litellm/proxy/client/cli/test_agents.py	Comprehensive unit + CliRunner tests for all agent helpers; uses DI stubs throughout so no real binaries or proxy are needed.
tests/local_testing/test_basic_python_version.py	New test_cli_extra_is_a_thin_client_install contract test verifies the cli extra has its three required deps and doesn't leak server-only packages.
tests/local_testing/test_router_debug_logs.py	Adds "Unclosed client session"/"Unclosed connector" to the noise-filter list; unrelated to the fallback-log assertions and doesn't weaken coverage.
packaging/homebrew/lite.rb	Homebrew formula template for the lite CLI extra; URL and sha256 are placeholder strings to be filled at release time per the accompanying README.

_{Reviews (5): Last reviewed commit: "test(router): filter aiohttp unclosed-se..." | Re-trigger Greptile}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 3 committers have signed the CLA.

✅ mateo-berri
❌ claude
❌ cursoragent
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[Sameerlite]

@greptileai

[Sameerlite]

LGTM

[mateo-berri]

@greptileai