AI Providers

SFDT’s AI features are optional and provider-agnostic. They work with Claude, Gemini, or OpenAI, configured during sfdt init or by editing .sfdt/config.json. Every AI command degrades gracefully when AI is disabled — heuristic fallbacks run where applicable (e.g. sfdt explain), and AI-only commands print how to enable it.

Enable AI


{
  "features": { "ai": true },
  "ai": { "provider": "claude", "model": "" }
}

Providers

Claude (default)

Requires the Claude Code CLI :


npm install -g @anthropic-ai/claude-code


{ "ai": { "provider": "claude" } }

Claude runs interactively and can read your repository files directly via tools, giving it full project context. No API key goes in sfdt config — Claude Code handles its own auth.

Claude’s interactive mode is not suitable for CI. Use Gemini or OpenAI for CI-based AI.

Gemini

Requires the Gemini CLI :


npm install -g @google/gemini-cli


{ "ai": { "provider": "gemini", "model": "" } }

Authentication and model selection are handled by the Gemini CLI. Suitable for CI.

OpenAI

Requires the Codex CLI :


npm install -g @openai/codex


{ "ai": { "provider": "openai", "model": "" } }

Authentication and model selection are handled by the Codex CLI. Suitable for CI.

HTTP endpoint (text-only)

For any OpenAI-compatible endpoint, set ai.provider to http — no CLI to install:


{ "ai": { "provider": "http", "baseURL": "https://…/v1", "model": "…", "apiKeyEnv": "AI_API_KEY" } }

Unlike the three CLI providers, http is plain text-completion and cannot run tools, so commands pre-gather context for it. Prompt content is passed through redactSensitiveData before it’s sent. The bounded auto-fix loop (deploy --smart --ai-fix with ai.agent.allowWrite) is CLI-providers-only for this reason.

Gateway headers

Some endpoints want an extra header beyond the API key — an org id, a routing tag, a proxy token. Use ai.headersEnv, which maps a header name to the name of the env var holding its value:


{
  "ai": {
    "provider": "http",
    "baseURL": "https://gateway.example/v1",
    "apiKeyEnv": "GATEWAY_KEY",
    "headersEnv": { "X-Org-Id": "GATEWAY_ORG_ID" }
  }
}

ai.headers also exists and takes literal values — fine for a non-secret routing tag, wrong for anything sensitive, because literals are written into .sfdt/config.json. headersEnv overrides a literal of the same name.

If a named env var is unset, the request fails naming that variable rather than calling the endpoint without the header. The same helper backs webhook channel auth — see Notifications.

Which commands use AI

Command	AI role
`sfdt test`	Failure analysis on test failure
`sfdt quality --fix-plan`	Prioritized, file-specific fix plan
`sfdt manifest --ai-cleanup`	Missing-dependency detection
`sfdt explain`	Deep log analysis (after the offline heuristic scan)
`sfdt review`	Code review across five categories
`sfdt pr-description`	GitHub/Slack content generation
`sfdt release`	Release-note generation
`sfdt changelog generate`	Changelog entries from commits
`sfdt deploy --smart --ai-fix`	Explain a failed deploy, or run the bounded auto-fix loop
`sfdt manifest --ai-cleanup`	Audit a draft `package.xml` for missing dependencies
`sfdt docs generate --roles`	Per-component, per-role documentation guides
`sfdt monitor`/`audit --notify`	Executive-summary digest (with `notifications.summary.enabled`)
`sfdt ai prompt`	Ad-hoc prompts

Non-interactive `--agent` mode

deploy, explain, review, and quality accept --agent, which runs the AI session non-interactively (it never blocks on input) — so coding agents and CI can drive these commands. Combine with --json for machine-readable output where supported.

Editable prompts

All AI behavior is driven by editable prompt templates (override per project under .sfdt/prompts.json):

deploy-error — deploy/validation error resolution.
doc-apex, doc-flow, doc-lwc, doc-object — per-metadata-type documentation guides (fall back to doc-role-guide).
monitor-summary — org-health executive summary for notification digests.

Disabling AI


{ "features": { "ai": false } }

All AI steps are skipped. AI-only commands (review, pr-description) exit with an error explaining how to enable it. Heuristic fallbacks still run in sfdt explain.

Security: the read-only tool sandbox

All AI invocations default to a read-only tool sandbox (Read,Grep,Glob) across the Claude/Gemini/Codex providers. AI-influenced content — diffs, org output, browser context — cannot drive Bash/Write/Edit. This closes the prompt-injection surface for both the streaming dashboard chat and the request/response CLI paths. Callers may pass an explicit allowed-tools list to override.