Claude Env Switcher

English | 中文

English

Claude Env Switcher manages Claude Code environment profiles for each workspace. It switches Anthropic-compatible and OpenAI-compatible providers without hand-editing .claude/settings.local.json.

Profiles are stored in VS Code user settings and can sync across machines. The active profile and generated runtime state remain workspace-local.

Design Goals

• Keep profile switching explicit, visible, and workspace-scoped.
• Avoid global detached background services.
• Start the OpenAI-compatible router only when Claude Code actually needs it.
• Keep each workspace isolated, even when multiple VS Code windows are open.
• Work the same way on local VS Code, Remote SSH, Linux, macOS, and Windows.

Key Features

• Manage named Claude Code profiles from a VS Code panel or quick pick.
• Switch native Anthropic-compatible environment variables.
• Use OpenAI-compatible APIs through the bundled Claude Code Router runtime.
• Configure router port mode per OpenAI-compatible profile:
  • Auto
  • Random in range
  • Preferred port with fallback
• Keep one router owner per workspace.
• Reuse one CCR runtime for multiple Claude sessions in the same workspace.
• Support owner/follower coordination when the same workspace is opened in multiple VS Code windows.
• Handle Claude Code token-count compatibility requests without starting CCR.
• Preserve Claude Code model context suffixes such as [1m] while sending clean model IDs upstream.
• Add files or folders to Claude Chat from the Explorer context menu.
• Optionally restart the extension host or reopen the latest Claude session after switching profiles.

OpenAI-Compatible Router Model

OpenAI-compatible profiles do not start CCR immediately when applied. Applying a profile only prepares workspace state:

• route token
• desired profile config
• workspace hook
• owner/follower coordination files

When Claude Code runs the UserPromptSubmit hook, the helper asks the current workspace owner to start the router. The owner then:

1. Selects the public endpoint port according to the profile strategy.
2. Starts the workspace endpoint.
3. Starts the embedded CCR process.
4. Confirms CCR is ready.
5. Writes the actual ANTHROPIC_BASE_URL back to .claude/settings.local.json.

Request flow:

Claude Code
  -> workspace endpoint
  -> embedded CCR
  -> OpenAI-compatible upstream

CCR is not a standalone global service. It is a child lifecycle resource of the current workspace owner plugin instance. When that owner closes, the endpoint and CCR exit as well. If another VS Code window has the same workspace open, it can become the next owner and rebuild the router on the next hook.

The compatibility endpoint POST /v1/messages/count_tokens is handled by the lightweight workspace endpoint itself. It does not start CCR, does not call the upstream provider, and does not store prompt content. The current bundled CCR baseline uses the same style of local heuristic estimate for this endpoint, so it is best treated as a compression-timing aid rather than provider-exact billing data.

GET /v1/models is also handled by the workspace endpoint. For Claude Code clients it returns Claude-style model metadata and context capability fields without starting CCR. If a configured model uses Claude Code's context suffix, for example gpt-4.1[1m], the suffix is kept visible to Claude Code but stripped before the request reaches the OpenAI-compatible upstream:

Claude-facing model:  gpt-4.1[1m]
Upstream model:       gpt-4.1

Cache And Usage Notes

Claude Env Switcher does not implement a local prompt/content cache. Cache hit-rate numbers, when available, come from upstream usage fields such as cached_tokens, cache_read_tokens, or cache_read_input_tokens returned by the OpenAI-compatible provider and normalized by the router runtime.

Dynamic local ports, workspace hashes, runtime ids, generation numbers, and route tokens are management-layer data and are not injected into the upstream request body. In practice, cache hit rate depends mostly on the upstream provider's own cache support, model/key/provider stability, and whether Claude Code sends a stable prompt prefix across requests. Some OpenAI-compatible services do not report cache usage fields, so their displayed cache ratio may be low or zero even when the provider has internal optimizations.

Multi-Window Behavior

For one workspace:

workspace X -> one owner -> one endpoint/CCR
other VS Code windows -> followers

Multiple Claude sessions in the same workspace share the same CCR runtime. Multiple VS Code windows for the same workspace do not each start their own CCR. This avoids profile, port, and route-token conflicts.

If the owner window closes, active streams through that owner may be interrupted. Later requests are handled by a follower after takeover.

Remote SSH Support

Remote SSH is a first-class scenario.

The extension runs as a workspace extension, so in a Remote SSH window the owner, helper, endpoint, CCR runtime, and .claude/settings.local.json all live on the remote machine. The router binds to 127.0.0.1 on the remote host, which is exactly where remote Claude Code runs.

This means:

• no local machine router is required
• no manual SSH port forwarding is required
• remote and local workspaces have separate runtime directories
• synced profiles can be reused, while applied settings stay remote-workspace-local

Quick Start

1. Install the extension.
2. Run Claude Env Switcher: Manage Profiles.
3. Add an Anthropic-compatible or OpenAI-compatible profile.
4. Apply the profile.
5. Start using Claude Code in that workspace.

Applied settings are written to:

.claude/settings.local.json

Security Notes

Profile definitions are stored in VS Code user settings. If VS Code Settings Sync is enabled, profile definitions may sync across machines. Workspace runtime files and active profile state stay local to the current workspace/machine.

Auth tokens are masked in the UI, but they are still stored in VS Code settings. Avoid storing production secrets in synced settings unless that matches your security model.

Third-Party Notices

This extension includes a slim headless router runtime for Anthropic-to-OpenAI-compatible request translation.

• Runtime core: @the-next-ai/ai-gateway, MIT License
• Claude Code Router compatibility reference: musistudio/claude-code-router, MIT License

Claude Env Switcher manages VS Code profiles, workspace lifecycle, hooks, owner/follower coordination, and Remote SSH behavior around that router runtime.

中文

Claude Env Switcher 用来按 workspace 管理 Claude Code 环境 Profile。它可以在 Anthropic-compatible 和 OpenAI-compatible Provider 之间切换，不需要手动编辑 .claude/settings.local.json。

Profile 定义存储在 VS Code 用户设置中，可以跟随 VS Code Settings Sync 同步；当前选中的 Profile 和运行态则保留在当前 workspace 本地。

设计思想

• Profile 切换必须明确、可见，并且以 workspace 为边界。
• 不启动全局 detached 后台服务。
• OpenAI-compatible 路由只在 Claude Code 真正需要时才启动。
• 每个 workspace 独立隔离，即使同一个 workspace 被多个 VS Code 窗口打开。
• 本地 VS Code、Remote SSH、Linux、macOS、Windows 使用同一套机制。

功能亮点

• 通过 VS Code 面板或 Quick Pick 管理命名 Profile。
• 支持原生 Anthropic-compatible 环境变量切换。
• 通过内置 Claude Code Router runtime 使用 OpenAI-compatible API。
• OpenAI-compatible Profile 可配置路由端口策略：
  • Auto
  • Random in range
  • Preferred port with fallback
• 同一个 workspace 只有一个 router owner。
• 同一个 workspace 内多个 Claude 会话共享同一个 CCR runtime。
• 同一个 workspace 被多个 VS Code 窗口打开时，使用 owner/follower 协调，避免多实例冲突。
• 处理 Claude Code token-count 兼容请求时不会启动 CCR。
• 保留 Claude Code 的 [1m] 等模型上下文后缀，同时向上游发送干净模型 ID。
• 支持从 Explorer 右键把文件或文件夹加入 Claude Chat。
• 切换 Profile 后可选择重启 extension host、重新打开最近 Claude 会话，或不做额外动作。

OpenAI-Compatible Router 模型

应用 OpenAI-compatible Profile 时不会立刻启动 CCR。此时只准备 workspace 状态：

• route token
• desired profile config
• workspace hook
• owner/follower 协调文件

当 Claude Code 执行 UserPromptSubmit hook 时，helper 会请求当前 workspace owner 启动路由。owner 随后会：

1. 根据 Profile 端口策略确定 public endpoint 端口。
2. 启动 workspace endpoint。
3. 启动内置 CCR 进程。
4. 确认 CCR ready。
5. 将真实的 ANTHROPIC_BASE_URL 写回 .claude/settings.local.json。

请求链路：

Claude Code
  -> workspace endpoint
  -> embedded CCR
  -> OpenAI-compatible upstream

CCR 不是独立全局服务，而是当前 workspace owner 插件实例的子生命周期资源。owner 关闭时，endpoint 和 CCR 也会退出。如果同一个 workspace 还有其他 VS Code 窗口打开，follower 可以在下一次 hook 时接管并重建路由。

兼容端点 POST /v1/messages/count_tokens 由轻量 workspace endpoint 自己处理。它不会启动 CCR，不会请求上游 Provider，也不会保存 prompt 内容。当前打包的 CCR 基线同样使用本地启发式估算这一接口，因此它更适合作为压缩时机参考，而不是精确的 Provider 计费数据。

GET /v1/models 也由 workspace endpoint 处理。对于 Claude Code 客户端，它会返回 Claude 风格的模型元信息和上下文能力字段，并且不会为了列模型启动 CCR。如果配置的模型带有 Claude Code 上下文后缀，例如 gpt-4.1[1m]，该后缀会继续暴露给 Claude Code，但真正请求 OpenAI-compatible 上游前会被剥离：

Claude-facing model:  gpt-4.1[1m]
Upstream model:       gpt-4.1

缓存与用量说明

Claude Env Switcher 不实现本地 prompt/content 缓存。缓存命中率如果可见，来源于 OpenAI-compatible Provider 返回的 usage 字段，例如 cached_tokens、cache_read_tokens 或 cache_read_input_tokens，再由 router runtime 做归一化。

动态本地端口、workspace hash、runtime id、generation 和 route token 都属于管理层数据，不会注入到上游请求 body。实际缓存命中率主要取决于上游 Provider 是否支持缓存上报、模型/key/Provider 是否稳定，以及 Claude Code 在多次请求中是否发送稳定的 prompt 前缀。部分 OpenAI-compatible 服务不会返回缓存用量字段，因此展示出来的缓存比例可能很低或为 0，即使 Provider 内部存在优化。

多窗口行为

对于同一个 workspace：

workspace X -> one owner -> one endpoint/CCR
other VS Code windows -> followers

同一个 workspace 内的多个 Claude 会话共享同一个 CCR runtime。同一个 workspace 的多个 VS Code 窗口不会各自启动一套 CCR，从而避免 Profile、端口和 route token 冲突。

如果关闭的是 owner 窗口，正在通过该 owner streaming 的请求可能会中断。后续请求会在 follower 接管后重新启动路由。

Remote SSH 支持

Remote SSH 是完整适配场景。

本插件是 workspace extension，因此在 Remote SSH 窗口中，owner、helper、endpoint、CCR runtime 和 .claude/settings.local.json 都运行或写入在远程机器上。路由绑定的是远程主机上的 127.0.0.1，这正是远程 Claude Code 所在的位置。

这意味着：

• 不需要本机启动 router
• 不需要手动配置 SSH 端口转发
• 远程 workspace 和本地 workspace 拥有独立 runtime 目录
• Profile 定义可以同步，但实际应用结果保留在远程 workspace 本地

快速开始

1. 安装插件。
2. 执行 Claude Env Switcher: Manage Profiles。
3. 添加 Anthropic-compatible 或 OpenAI-compatible Profile。
4. 应用 Profile。
5. 在当前 workspace 中使用 Claude Code。

应用后的设置写入：

.claude/settings.local.json

安全说明

Profile 定义存储在 VS Code 用户设置中。如果开启 VS Code Settings Sync，Profile 定义可能会同步到其他机器。workspace runtime 文件和当前激活状态仍保留在当前 workspace/机器本地。

认证 token 会在 UI 中隐藏，但仍然存储在 VS Code 设置里。是否把生产密钥放进同步设置中，应按你的安全模型决定。

第三方声明

本插件内置了一个轻量 headless router runtime，用于 Anthropic 到 OpenAI-compatible 的请求转换。

• Runtime 核心：@the-next-ai/ai-gateway，MIT License
• Claude Code Router 兼容参考：musistudio/claude-code-router，MIT License

Claude Env Switcher 负责围绕该 router runtime 管理 VS Code Profile、workspace 生命周期、hook、owner/follower 协调以及 Remote SSH 场景。