ACP agents
Use this guide when you want to bring Claude Code, Codex, or other agent CLIs into Faheem Code. Faheem Code can drive conversations with the built-in Faheem Code agent or with an external ACP agent. For an ACP agent, the selected backend launches the provider's CLI and must have access to its subscription login or API key.
What is an ACP agent?
The Agent Client Protocol (ACP) is a standard for talking to coding agents over JSON-RPC on stdio. Instead of Faheem Code calling an LLM directly, the Agent Server spawns the agent's own CLI as a subprocess and relays each turn to it. The external agent manages its own LLM, tools, and execution; Faheem Code sends messages and renders what comes back.
The Agent Server owns the subprocess and the credentials; Faheem Code only records which agent to run and surfaces a form for the secrets it needs. The agent choice is stored per backend, so switching backends can switch agents.
Supported providers
| Provider | Default command |
|---|---|
| Claude Code | npx -y @agentclientprotocol/claude-agent-acp |
| Codex | npx -y @zed-industries/codex-acp |
| Gemini CLI | npx -y @google/gemini-cli --acp |
The provider list is sourced from the Faheem Code SDK registry (faheemcode.sdk.settings.acp_providers, mirrored into @faheem-code/typescript-client) and enriched with Canvas UI metadata. Adding or changing a provider happens upstream in the SDK.
Authentication
A "subscription login" is the credential the provider's own CLI stores when you sign in once — a file in your home directory, or, for Claude Code on macOS, the system Keychain. When the Agent Server runs on that same machine (a local or self-hosted backend), the provider CLI finds that login automatically — no API key required. On a clean cloud sandbox there's no stored login, so an API key is needed instead.
| Provider | Subscription login (auto-detected) | API key |
|---|---|---|
| Claude Code | A Claude Code login (Pro/Max), from Claude Code's own credential store: the macOS Keychain, or ~/.claude/.credentials.json on Linux | ANTHROPIC_API_KEY |
| Codex | A ChatGPT login (codex login) cached at ~/.codex/auth.json | OPENAI_API_KEY |
| Gemini CLI | Your Google login (gemini/gemini --acp) cached at ~/.gemini/oauth_creds.json | GEMINI_API_KEY |
All three collect an optional API key (plus base URL) in onboarding. As noted above, a subscription / OAuth login takes priority over an API key — when the provider's CLI is signed in, a key set in the environment is not used:
- Codex —
codex login statuskeeps reporting the ChatGPT login even withOPENAI_API_KEYset. - Gemini CLI — uses the OAuth auth type chosen at
geminilogin;GEMINI_API_KEYis only consulted if you switch the auth type. The free Google login is the common no-key path locally — sign in once and it just works. - Claude Code — with both present,
claude auth statusreports it is authenticated via the subscription (claude.ai), not the key. The login is auto-detected from the macOS Keychain (or~/.claude/.credentials.jsonon Linux);CLAUDE_CONFIG_DIRis not required for it — it only relocates Claude Code's config directory (settings/history, not the token) and signals the SDK to strip a conflictingANTHROPIC_API_KEY/ANTHROPIC_BASE_URL.
The one exception is the base URL (*_BASE_URL): a custom value points the CLI at a different endpoint (a proxy or gateway) and does take effect even under a login — for Gemini it rides the ACP gateway param. It's an advanced override, not needed for normal use.
Onboarding an ACP agent
First-time users get a four-step onboarding modal. To onboard an ACP agent:
- Choose agent — pick Claude Code, Codex, or Gemini CLI instead of Faheem Code. The choice is saved immediately to your backend's settings.
- Check backend — confirms Faheem Code can reach the Agent Server.
- Set up credentials — enter the provider's API key (and, optionally, a custom base URL for a proxy or gateway). All three providers collect these here, and every field is optional.
- Say hello — creates your first conversation and closes the modal.
How credentials reach the agent
Each credential you enter is saved as a global secret whose name is exactly the environment variable the Agent Server exports into the ACP subprocess (e.g. ANTHROPIC_API_KEY). Saving in onboarding is identical to adding the secret under Settings → Secrets, where you can edit or remove it anytime. Keeping the secret name equal to the env var is what makes a saved key actually reach the provider CLI.
Switching agent or model later
Open Settings → Agent at any time:
- Agent — switch between Faheem Code and ACP.
- Preset — pick a built-in provider (Claude Code, Codex, Gemini CLI) or Custom to point at any other ACP server.
- Command — the command line used to spawn the subprocess. Selecting a preset fills this in; editing it to match another preset re-detects that provider. API keys are not entered here — they live in the Secrets panel.
- Model — choose a suggested model for the provider or enter a custom model override. Built-in providers save a concrete model rather than leaving it blank.
Saving writes an agent_settings_diff (agent_kind, acp_server, acp_command, acp_model) to PATCH /api/settings. A running conversation keeps the agent it started with; the new choice applies to conversations you start afterward.
Custom ACP servers
Any stdio ACP server works: choose Custom in Settings → Agent and enter its launch command. Custom servers have no curated model list, so enter the model ID the server expects (if any) as a custom model. Pass credentials by adding the env vars the server reads as global secrets under Settings → Secrets.