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
true if value is a valid AgentProviderId
agentProviderLabel
Returns human-readable label for a provider.
function agentProviderLabel(provider: AgentProviderId): string
agentProviderMarkerDir
Returns the marker directory name for a provider.
function agentProviderMarkerDir(provider: AgentProviderId): string
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
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
{ kind: "auto" } - Auto-detect providers{ kind: "all" } - Use all providers{ kind: "providers", providers: [...] } - Specific providersnull - 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[]>
Absolute path to repository root
- 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
function formatAgentProviderList(providers: AgentProviderId[]): string
providers
AgentProviderId[]
required
List of provider IDs
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;
}