copilot-local

A wrapper CLI for GitHub Copilot CLI that makes it easy to use local LLMs. It reads environment variables from a config file and launches the copilot command with them set.

Motivation

Claude Code supports loading environment variables from a JSON config file, which makes it easy to redirect API calls to any local LLM. GitHub Copilot CLI has no equivalent feature, so switching the API endpoint requires manually setting environment variables each time. This small wrapper brings the same convenience to Copilot CLI.

Requirements

• Node.js 22+
• GitHub Copilot CLI

Installation

npm install -g @blauerberg/copilot-local
# or run on demand with npx
npx @blauerberg/copilot-local <model>

Configuration

Generate a config file automatically

If your LLM server exposes an OpenAI-compatible /v1/models endpoint (llama.cpp, LM Studio, Ollama 0.1.24+, etc.), you can generate a config template automatically:

copilot-local generate-config --models-endpoint http://localhost:11434/v1/models \
  > ~/.config/copilot-local/settings.json

This fetches the model list from the endpoint and writes a template with all required environment variables pre-filled. Open the file and replace <YOUR_API_KEY> with the actual API key (or any non-empty string if the server doesn't require one).

Manual setup

Alternatively, create ~/.config/copilot-local/settings.json manually and define one or more local models:

{
  "gpt-oss-20b": {
    "COPILOT_PROVIDER_BASE_URL": "http://localhost:11434/v1",
    "COPILOT_PROVIDER_API_KEY": "dummy",
    "COPILOT_PROVIDER_TYPE": "openai",
    "COPILOT_MODEL": "gpt-oss-20b",
    "COPILOT_PROVIDER_MAX_PROMPT_TOKENS": 32000,
    "COPILOT_PROVIDER_MAX_OUTPUT_TOKENS": 64000,
    "COPILOT_OFFLINE": true
  }
}

Each key-value pair is exported as an environment variable before copilot is invoked. Run copilot help providers for details on available environment variables.

Usage

Run with a model

copilot-local <MODEL> [--config FILE] [-- copilot args]

| Argument | Description | | --------------- | -------------------------------------------------------------------------- | | MODEL | Profile name defined in the config file (required) | | --config FILE | Path to the config file (default: ~/.config/copilot-local/settings.json) | | args after -- | Passed through directly to copilot |

If no arguments are passed after the model name, copilot -i "" is launched in interactive mode.

# Interactive mode
copilot-local gpt-oss-20b

# Pass arguments to copilot
copilot-local gpt-oss-20b -- version

# Use a custom config file
copilot-local gpt-oss-20b --config ~/my-settings.json

Generate a config template

copilot-local generate-config --models-endpoint <URL>

| Option | Description | | --- | --- | | --models-endpoint <URL> | OpenAI-compatible /v1/models endpoint (required) |

Prints a JSON config template to stdout. Redirect to a file to save it:

copilot-local generate-config --models-endpoint http://localhost:11434/v1/models \
  > ~/.config/copilot-local/settings.json

Shell Completion

Tab completion for model names can be enabled with the completions command.

zsh — add to ~/.zshrc:

eval "$(copilot-local completions zsh)"

bash — add to ~/.bashrc:

eval "$(copilot-local completions bash)"

After reloading your shell, pressing <Tab> after copilot-local will show the model names defined in your config file as candidates.

Troubleshooting

Error: 'copilot' command not found GitHub Copilot CLI is not installed or not in your PATH. Follow the installation guide and make sure copilot is available in your shell.

Error: config file not found The config file does not exist at the default path (~/.config/copilot-local/settings.json). Create the file as shown in the Configuration section, or pass a custom path with --config.

Error: '<model>' not found The model name you passed does not exist in the config file. The error message lists the available model names.

See also

• Use BYOK models with Copilot CLI