Configuration for a CLI-based LLM provider.

Pure data — loaded from TOML or constructed in code. This is what makes CLIProvider universal: a new CLI client is just a config entry, no Elixir code needed.

Core Fields

• name — atom identifying this provider (e.g. :claude_code, :droid)
• binary — executable name (must be in PATH)
• subcommand — optional subcommand prepended to args (e.g. "exec" for droid)
• provider_type — always :cli
• default_timeout — timeout in ms (default: 1_800_000 = 30 min)
• default_model — real model string used only when GC owns the default
• model_resolution — how model selection works for this CLI provider: :gc_default, :provider_runtime, or :explicit_only
• flags — map of opt key → CLI flag (e.g. %{model: "--model", auto: "--auto"})
• prompt_position — :last (default) or :flagged (e.g. claude uses -p)
• prompt_flag — flag before the prompt when prompt_position == :flagged (e.g. -p)
• prefix_args — args always prepended (e.g. ["--print"] for claude)
• stdin_hack — wrap with /bin/sh -c 'exec "$0" "$@" < /dev/null' (claude needs this)
• install_hint — shown in not_installed error message
• prompt_transport — optional semantic prompt transport (:last, :flagged, :stdin)
• system_prompt_transport — optional semantic system prompt strategy
• cwd_flag — optional explicit cwd flag for capability introspection
• add_dir_flag — optional explicit add-dir flag for capability introspection
• output_mode — optional output mode (:stdout_text, :final_message_only, :json)
• non_interactive_args — optional args enabling non-interactive execution
• auto_approve_args — optional args enabling unattended execution
• sandbox_bypass_args — optional args for stronger sandbox/approval bypass
• preflight — optional declarative preflight configuration

System Prompt File Transform

• system_prompt_file_transform — declares how to prepare the system prompt file before passing it to the CLI. When nil, the file is passed as-is (backward-compatible default).

  Supported transforms:

  • :agent_spec_yaml — generates a YAML agent spec file plus a sibling system.md containing the raw prompt. Used by Kimi CLI's --agent-file. Generates the nested structure Kimi expects:

    version: 1
    agent:
      extend: default
      name: <agent_name>
      system_prompt_path: ./system.md
      model: <model>    # when available

  The transform resolves field values with this precedence:

  1. Dispatch opts (:agent_name, :model) — caller-supplied
  2. file_transform_defaults (TOML config) — provider-level defaults
  3. Built-in fallbacks (name: "llm_core_agent", version: 1, extend: "default")

• file_transform_defaults — optional map of default values for the transform. Providers declare these in TOML under [providers.<id>.cli.file_transform_defaults]. Keys like version, extend, name, model are passed to the transform as fallback context.

Output Capture

• output_file_flag — CLI flag that writes the final response to a file (e.g. "--output-last-message" for Codex). When set, the runtime creates a temp file, passes it via this flag, and reads the response from the file instead of stdout.
• output_strip_patterns — list of regex pattern strings applied to stdout output to strip banners, session noise, or decorators before building the response. Applied only to stdout-based output (not file capture).