Commands Desktop  ──>  Provider Plugin  ──>  OpenAI / Gemini API

These plugins are experimental.

• They are adapter layers around external APIs, not vendor-native runtimes.
• They may drift as provider SDKs, APIs, auth flows, or product policies change.
• Depending on the provider, account type, and usage pattern, they may violate vendor terms of service, acceptable use policies, or product expectations.
• You are responsible for checking whether a given plugin is acceptable for your account and workflow before using it.

If a built-in native provider in Commands Desktop already works for your use case, prefer that instead.

Most of the time, you should prefer native CLI-backed providers in Commands Desktop.

This repo still makes sense when you want one of these tradeoffs:

• Gemini with a provider-controlled integration path: gemini_cli is native and fast, but Gemini CLI does not currently offer strong sandboxing. The gemini plugin can be a better fit when you want Gemini-like performance through a more traditional provider boundary.
• API-key-driven integration: use a provider via API credentials rather than an installed CLI runtime.
• Desktop-managed provider config: keep auth and model settings in the provider profile instead of a separate CLI environment.
• Alternative tool/runtime behavior: experiment with plugin-side tool surfaces, MCP support, or provider-specific request shaping.

The strongest reason to use this repo today is probably the Gemini plugin.

Skip these plugins when:

• Commands already has a native CLI provider that gives you the behavior you want.
• You want maximum fidelity to the vendor’s own runtime.
• You need the cleanest permission/containment model.
• You want the lowest-maintenance integration path.

• Node.js 18+
• Commands Desktop (DMG, installer, or dev build)

git clone https://github.com/Commands-com/agent-plugins.git
cd agent-plugins

Install all plugins:

macOS / Linux:

./scripts/install-plugins.sh

Windows (or any platform with Node.js):

node scripts/install-plugins.mjs

Install just one plugin, for example gemini:

macOS / Linux:

./scripts/install-plugins.sh --plugin gemini

Windows (or any platform with Node.js):

node scripts/install-plugins.mjs --plugin gemini

Both scripts copy the selected plugins, install npm dependencies, and generate providers-allowed.json next to the providers directory so Commands can verify the installed plugins by SHA-256.

Then in Commands Desktop:

1. Restart the app if it was already running.
2. Create or edit an agent profile and select provider openai or gemini.

Dev Mode + Trust All Plugins is still available as a local-development bypass, but it is no longer required for plugins installed through the verified allowlist flow.

List available plugin IDs:

./scripts/install-plugins.sh --list
node scripts/install-plugins.mjs --list

• Default model: gpt-5.4
• SDK: @openai/agents
• Auth: Desktop profile apiKey field, or Codex OAuth token at ~/.codex/auth.json
• Features: file-system tools, MCP server support, session compaction

• Default model: gemini-3.1-pro-preview
• Available models: gemini-3.1-pro-preview, gemini-2.5-flash, gemini-2.0-flash
• Auth: Desktop profile apiKey field, or Gemini OAuth creds at ~/.gemini/oauth_creds.json
• Features: model fallback, retry with exponential backoff, thought signature injection
• Best use case: when you want Gemini through a provider plugin path instead of gemini_cli

• Models: echo-v1, echo-v2
• No external API calls — deterministic local text transforms
• Use as a template for building your own provider

cp -R ./plugins/echo-sample ./plugins/my-provider

Update:

• package.json — set commands.providerId, defaultModel, desktopEntry
• index.mjs — implement runPrompt() with your LLM API
• desktop.mjs — define configSchema, listModels(), validate(), buildEnv()

Reinstall:

./scripts/install-plugins.sh        # macOS/Linux
node scripts/install-plugins.mjs    # Windows (or any platform)

Or install only your provider:

./scripts/install-plugins.sh --plugin gemini
node scripts/install-plugins.mjs --plugin gemini

Restart Commands Desktop. Your provider appears in agent create/edit.

External providers load when they are present in the verified provider allowlist.

The installer in this repo writes:

• ~/.commands-com/workspace/providers
• ~/.commands-com/workspace/providers-allowed.json

commands-com start

Optional custom plugin path:

COMMANDS_AGENT_PROVIDERS_DIR=/custom/providers/path

For local development without an allowlist, you can still bypass verification:

COMMANDS_AGENT_DEV=1 \
COMMANDS_AGENT_TRUST_ALL_PLUGINS=1 \
commands-com start

If you only want Gemini, you can install only that provider.

mkdir -p ~/.commands-com/workspace/providers

rsync -a --delete ./plugins/gemini/ ~/.commands-com/workspace/providers/gemini/

npm install --prefix ~/.commands-com/workspace/providers/gemini --omit=dev

node ./scripts/generate-provider-allowlist.mjs \
  --managed-only \
  ~/.commands-com/workspace/providers \
  ~/.commands-com/workspace/providers-allowed.json

rsync -a --delete ./plugins/openai/ ~/.commands-com/workspace/providers/openai/
rsync -a --delete ./plugins/gemini/ ~/.commands-com/workspace/providers/gemini/

npm install --prefix ~/.commands-com/workspace/providers/openai --omit=dev
npm install --prefix ~/.commands-com/workspace/providers/gemini --omit=dev

node ./scripts/generate-provider-allowlist.mjs \
  --managed-only \
  ~/.commands-com/workspace/providers \
  ~/.commands-com/workspace/providers-allowed.json

$dest = "$env:LOCALAPPDATA\commands-com\workspace\providers"
New-Item -ItemType Directory -Force -Path "$dest\gemini"

robocopy .\plugins\gemini "$dest\gemini" /MIR /XD node_modules

npm install --prefix "$dest\gemini" --omit=dev

New-Item -ItemType Directory -Force -Path "$dest\openai", "$dest\gemini"

robocopy .\plugins\openai "$dest\openai" /MIR /XD node_modules
robocopy .\plugins\gemini "$dest\gemini" /MIR /XD node_modules

npm install --prefix "$dest\openai" --omit=dev
npm install --prefix "$dest\gemini" --omit=dev

git pull
./scripts/install-plugins.sh        # macOS/Linux
node scripts/install-plugins.mjs    # Windows (or any platform)

Single-provider update:

./scripts/install-plugins.sh --plugin gemini
node scripts/install-plugins.mjs --plugin gemini

rm -rf ~/.commands-com/workspace/providers/openai ~/.commands-com/workspace/providers/gemini

rm -rf ~/.commands-com/workspace/providers/gemini

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\commands-com\workspace\providers\openai", "$env:LOCALAPPDATA\commands-com\workspace\providers\gemini"

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\commands-com\workspace\providers\gemini"

plugins/openai           OpenAI provider (index.mjs, desktop.js)
plugins/gemini           Gemini provider (index.mjs, desktop.js)
plugins/echo-sample      Reference provider (index.mjs, desktop.mjs)
scripts/install-plugins.sh    Bash installer (macOS/Linux)
scripts/install-plugins.mjs   Node.js installer (cross-platform)
scripts/generate-provider-allowlist.mjs  Generate provider allowlist with SHA-256 pins
docs/CONTRACT.md         Full provider contract specification
GETTING_STARTED.md       Step-by-step setup guide

• Getting Started
• Contributing
• Provider Contract