CLI Providers

AgentOS can use locally installed CLI tools as LLM providers, so a user's existing subscription (Anthropic Max, a Google account) serves the calls without an API key. A ChatGPT subscription is reached through an OAuth flow rather than a CLI (below).

Architecture

CLI providers use the subprocess bridge pattern — each provider spawns the CLI binary via execa, pipes prompts through stdin, and parses structured JSON/NDJSON output from stdout.

IProvider (AgentOS interface)
    │
    ▼
ClaudeCodeProvider / GeminiCLIProvider     ← message formatting, tool schema injection, response mapping
    │
    ▼
ClaudeCodeCLIBridge / GeminiCLIBridge      ← extends CLISubprocessBridge (flag assembly, error classification)
    │
    ▼
CLISubprocessBridge (abstract base)        ← sandbox/subprocess/ — spawn, pipe, NDJSON parse, timeout/abort
    │
    ▼
execa → local CLI binary                   ← user's authenticated CLI (claude, gemini, codex)

Core Subprocess Module

The generalized subprocess bridge lives at src/safety/sandbox/subprocess/:

• CLISubprocessBridge — abstract base class (template method pattern). Owns process lifecycle: spawn, stdin pipe, NDJSON line splitting, timeout, abort signal. Subclasses implement buildArgs(), classifyError(), parseStreamEvent().
• CLISubprocessError — generic error with open string codes, guidance (user-facing fix instructions), and recoverable flag. Works for any binary, not just LLM CLIs.
• CLIRegistry — PATH scanner that discovers installed CLIs. It loads 54 bundled descriptors from the JSON files in registry/ (LLM CLIs such as claude, gemini and ollama, dev tools, runtimes, package managers, cloud CLIs, databases, media and networking tools), and register() adds more.

Available CLI Providers

Provider ID	Binary	Auth	Default Model	Status
claude-code-cli	claude	Anthropic Max subscription	claude-sonnet-4-6	Confirmed — officially supported by Anthropic
gemini-cli	gemini	Google account login	gemini-3.5-flash	Use at your own risk — see ToS warning below

Terms of Service Compliance

claude-code-cli — CONFIRMED SAFE

Anthropic explicitly supports programmatic use of Claude Code CLI via the -p (print) flag. Their headless mode documentation provides examples for CI/CD pipelines, shell scripts, GitHub Actions, and subprocess invocation.

Key points from Anthropic's legal and compliance page:

• Calling claude -p from scripts and automation is the intended use case
• The --bare flag is recommended for reproducible scripted calls
• Max plan usage limits "assume ordinary, individual usage"
• Extracting or reusing OAuth tokens from Claude Code in other tools is explicitly prohibited

What AgentOS does: Spawns claude --bare -p --output-format json as a subprocess. Never extracts, proxies, or stores OAuth tokens. Each invocation uses the user's own locally-authenticated Claude Code installation. This is the pattern Anthropic designed and documents.

gemini-cli — USE AT YOUR OWN RISK

WARNING: Google's Gemini CLI Terms of Service contain language that could be interpreted as prohibiting third-party subprocess invocation when using Google account (OAuth) authentication. While Google's own automation tutorial promotes headless scripted use, their ToS also states:

"Directly accessing the services powering Gemini CLI using third-party software, tools, or services is a violation of applicable terms and policies, and such actions may be grounds for suspension or termination of your account."

Google has enforced this aggressively — users report account suspensions for using third-party tools with Gemini CLI OAuth. A first-offense reinstatement process exists but requires manual appeal.

Safer alternative: Use the gemini provider with GEMINI_API_KEY from Google AI Studio. This uses the Gemini API directly (separate ToS) and carries no third-party usage risk. The gemini-cli provider is available for users who understand and accept the risk.

What AgentOS does: Spawns gemini -p --output-format json as a subprocess. System prompts are injected via a temporary file + the GEMINI_SYSTEM_MD environment variable (Gemini CLI's official mechanism). Never extracts or stores OAuth tokens.

OpenAI Codex CLI — OAuth flow

OpenAI's approach is the most permissive. The Codex CLI is Apache 2.0 licensed, and an OpenAI maintainer confirmed that the terms are "quite permissive" toward third-party tools doing similar things.

AgentOS exports an OpenAIOAuthFlow from @framers/agentos/auth that uses the Codex CLI's public OAuth client ID (app_EMoamEEZ73f0CkXaXp7hrann) and its browser PKCE flow on localhost:1455, then exchanges the id_token for an API key as the Codex CLI's obtain_api_key() does. OpenAIProvider takes the flow as oauthFlow and calls it for a token on each request (OAuth Auth). There is no codex CLI provider.

Provider Details

claude-code-cli

• Binary: claude (install: npm install -g @anthropic-ai/claude-code)
• Auth: User logs into Claude Code separately by running claude in terminal
• System prompt: --system-prompt flag (direct)
• Tool calling: tool schemas written into the system prompt; when tools are present, --json-schema constrains the reply to text or tool calls (a reply that does not parse as that shape is retried once without the schema and returned as text)
• Streaming: --output-format stream-json with --verbose --include-partial-messages
• Key flags: --bare (skip plugins/hooks), --max-turns 1 (single completion)
• Models: claude-opus-5-5, claude-fable-5-1, claude-fable-5, claude-sonnet-5-5, claude-sonnet-5, claude-sonnet-4-6 (default), claude-haiku-4-5-20251001
• Cost: $0 per token (subscription)
• Auto-detection: Checks if claude is on PATH (after API-key providers, before Ollama)

gemini-cli

• Binary: gemini (install: npm install -g @google/gemini-cli)
• Auth: User logs in via Google account by running gemini in terminal
• System prompt: Temp file + GEMINI_SYSTEM_MD env var (no --system-prompt flag)
• Tool calling: XML prompt-based with <tool_call> markers (no --json-schema support)
• Streaming: --output-format stream-json
• Key flags: -p (headless), -m (model selection)
• Models: gemini-3.5-flash (default), gemini-3.1-pro-preview, gemini-3.5-flash-lite, gemini-2.5-flash-lite. The CLI answers gemini-2.5-flash with gemini-3.5-flash and returns 404 for gemini-2.5-pro.
• Cost: $0 per token (Google account — free tier: 60 req/min, 1000 req/day; higher with AI Pro/Ultra)
• Auto-detection: Checks if gemini is on PATH (after claude-code-cli, before Ollama)

Adding a New CLI Provider

To add support for a new CLI binary:

1. Create {Name}CLIBridge extends CLISubprocessBridge — implement buildArgs(), classifyError(), parseStreamEvent()
2. Create {Name}CLIProviderError extends CLISubprocessError — define CLI-specific error codes
3. Create {Name}CLIProvider implements IProvider — message formatting, tool calling strategy, response mapping
4. Register in CLIRegistry.WELL_KNOWN_CLIS if it should be auto-discovered
5. Register the provider id in AIModelProviderManager, and add its default models and its PATH probe to PROVIDER_DEFAULTS and AUTO_DETECT_ORDER in provider-defaults.ts

The CLISubprocessBridge base class handles the spawn, the stdin pipe, NDJSON parsing, timeouts and health checks; subclasses implement what is specific to their CLI.

Auto-Detection Order

When no provider is explicitly configured, AgentOS probes in this order:

1. openrouter      → OPENROUTER_API_KEY
2. openai          → OPENAI_API_KEY
3. anthropic       → ANTHROPIC_API_KEY
4. gemini          → GEMINI_API_KEY
5. groq            → GROQ_API_KEY
6. together        → TOGETHER_API_KEY
7. mistral         → MISTRAL_API_KEY
8. xai             → XAI_API_KEY
9. requesty        → REQUESTY_API_KEY
10. claude-code-cli → `which claude` (PATH detection)
11. gemini-cli     → `which gemini` (PATH detection)
12. ollama         → OLLAMA_BASE_URL

API-key providers take priority (explicitly configured). CLI providers come next (subscription-grade models). Ollama is last (local/free).