Agent Providers

Functions and types for managing supported coding agent providers

Overview

The agent providers module handles detection, configuration, and management of supported coding agents (Codex, Claude Code, Gemini CLI).

Types

AgentProviderId

Supported agent provider identifiers.

type AgentProviderId = "codex" | "claude-code" | "gemini-cli";

Constants

AGENT_PROVIDER_ORDER

Default ordering for agent providers.

const AGENT_PROVIDER_ORDER: AgentProviderId[] = [
  "codex",
  "claude-code",
  "gemini-cli"
];

Functions

isAgentProviderId

Type guard to check if a value is a valid agent provider ID.

function isAgentProviderId(value: unknown): value is AgentProviderId

value · unknown · required

Value to check

Returns: true if value is a valid AgentProviderId

agentProviderLabel

Returns human-readable label for a provider.

function agentProviderLabel(provider: AgentProviderId): string

provider · AgentProviderId · required

Provider identifier

Returns: Display label (e.g., “Codex”, “Claude Code”, “Gemini CLI”)

agentProviderMarkerDir

Returns the marker directory name for a provider.

function agentProviderMarkerDir(provider: AgentProviderId): string

provider · AgentProviderId · required

Provider identifier

Returns: Marker directory name (e.g., “.codex”, “.claude”, “.gemini”)

normalizeAgentProviderList

Normalizes a list of provider names into valid provider IDs.

function normalizeAgentProviderList(
  values: Iterable<unknown>
): AgentProviderId[]

values · Iterable<unknown> · required

Raw provider names or identifiers

Returns: Normalized and deduplicated list of valid provider IDs

Example:

normalizeAgentProviderList(['claude', 'gemini', 'claude'])
// Returns: ['claude-code', 'gemini-cli']

parseProvidersFlag

Parses command-line provider flag into structured result.

function parseProvidersFlag(
  raw: string | null | undefined
): { kind: "auto" | "all" } | { kind: "providers"; providers: AgentProviderId[] } | null

raw · string | null | undefined · required

Raw flag value

Returns:

• { kind: "auto" } - Auto-detect providers
• { kind: "all" } - Use all providers
• { kind: "providers", providers: [...] } - Specific providers
• null - Invalid or empty input

Example:

parseProvidersFlag('codex,claude')
// Returns: { kind: 'providers', providers: ['codex', 'claude-code'] }

parseProvidersFlag('auto')
// Returns: { kind: 'auto' }

detectAgentProvidersForRepo

Detects which agent providers are configured for a repository.

async function detectAgentProvidersForRepo(
  repoRoot: string
): Promise<AgentProviderId[]>

repoRoot · string · required

Absolute path to repository root

Returns: List of detected providers based on marker files/directories

Detection Logic:

• Codex: Checks for .codex/ directory
• Claude Code: Checks for .claude/, CLAUDE.md, or CLAUDE.local.md
• Gemini CLI: Checks for .gemini/ directory

Example:

const providers = await detectAgentProvidersForRepo('/path/to/repo');
// Returns: ['codex', 'claude-code'] if both markers found

formatAgentProviderList

Formats a provider list for display.

function formatAgentProviderList(providers: AgentProviderId[]): string

providers · AgentProviderId[] · required

List of provider IDs

Returns: Comma-separated display labels or “(none)”

Example:

formatAgentProviderList(['codex', 'claude-code'])
// Returns: "Codex, Claude Code"

formatAgentProviderList([])
// Returns: "(none)"

Usage Example

import {
  detectAgentProvidersForRepo,
  parseProvidersFlag,
  formatAgentProviderList,
} from './lib/agent-providers';

// CLI argument parsing
const flagResult = parseProvidersFlag(process.argv[2]);
let providers;

if (!flagResult || flagResult.kind === 'auto') {
  // Auto-detect from repository
  providers = await detectAgentProvidersForRepo(process.cwd());
  console.log('Detected:', formatAgentProviderList(providers));
} else if (flagResult.kind === 'all') {
  providers = AGENT_PROVIDER_ORDER;
} else {
  providers = flagResult.providers;
}