llmgate

llmgate configures Claude Code to use a LiteLLM-compatible gateway.

Run the setup wizard without installing it first:

npx llmgate

Print a non-interactive status report that can be copied into an issue or support request:

npx llmgate status

Run status without contacting the configured gateway:

npx llmgate status --local

Requires Node.js 20.19.0 or newer.

The wizard:

• shows what it will inspect before reading local configuration;
• checks the current Claude Code setup after you approve read-only diagnostics;
• validates the gateway token by listing models from the LiteLLM-compatible gateway;
• lets you select a model from the gateway response;
• shows an apply plan with masked secret values before making changes;
• writes terminal, Claude Code user settings, and detected VS Code/Cursor settings;
• creates backups before file writes, reports backup paths, and reruns diagnostics before reporting success.

Supported targets:

• macOS and Linux shell rc files for zsh, bash, and fish;
• Windows user environment variables;
• Claude Code user settings at ~/.claude/settings.json;
• VS Code and Cursor user settings when their config directories already exist.

What llmgate reads and writes

Interactive setup asks before reading local configuration. If you continue, llmgate may inspect:

• Claude Code user settings at ~/.claude/settings.json;
• your detected shell profile or Windows user environment variables;
• VS Code and Cursor user settings paths;
• project Claude settings under ./.claude/;
• the current process environment;
• claude --version output.

If existing gateway credentials are found, setup and llmgate status may contact the configured gateway to list models and send a tiny ping model test request. Tokens are sent only to the configured gateway and are masked in output. Use llmgate status --local for a read-only local report with no gateway network checks.

No files or environment variables are changed until you approve the final apply plan. File writes create .llmgate.bak backups when replacing existing files and print the backup paths. Windows user environment updates do not have a file backup; the apply plan shows old and new values instead.

Use fake tokens in examples and replace the placeholder gateway with your own LiteLLM-compatible gateway URL.

Local development:

npm install
npm run dev

Check, typecheck, and test:

npm run check
npm run typecheck
npm test

Build the distributable CLI:

npm run build

Publishing

Publishing is handled by GitLab CI.

Merge requests run checks, typechecks, tests, and a build. Default-branch pushes compute the next version from conventional commits, publish the package to npm, and create a GitLab release.