claude-xcode-agent
A shell-based launcher that runs Claude Code as an Xcode 27 agent using your own API key or gateway.
At a Glance
MIT-licensed wrapper script that runs Claude Code as an Xcode 27 agent using your own API key or gateway. API usage costs are external.
Engagement
Available On
Alternatives
Listed Nov 2026
About claude-xcode-agent
claude-xcode-agent is an open-source, MIT-licensed project from GitHub user yusuke-114 that lets Xcode 27 use Claude Code as its coding agent with your own Anthropic API key or a gateway. It wraps the ACP adapter (claude-agent-acp) with a launcher script, claude-acp.sh, that reads its settings from a config file.
What It Is
Xcode talks to agents over the Agent Client Protocol (ACP), and an adapter bridges ACP to Claude Code. Used on its own, that adapter has two problems: Xcode launches agents from the GUI, so there is no shell environment to hold a key or gateway URL, and the adapter hardcodes --setting-sources user,project,local, so the global ~/.claude/settings.json is applied inside Xcode as well. The launcher script addresses both.
How the Launcher Works
The script runs in two roles. As the agent, it loads config.json into the environment, points CLAUDE_CODE_EXECUTABLE at itself and execs the adapter. As claude, it swaps the setting sources for project,local, adds any configured MCP servers and execs the real claude. Both steps use exec, so no wrapper process stays alive and stdout remains pure ACP.
Setup and Configuration
Cloning the repository and running setup.sh installs node, claude and the adapter, then prints the path of claude-acp.sh. That path goes into Xcode under Settings › Intelligence › Add an Agent… as the Executable. All fields in the optional config.json can be left out, in which case claude uses its own login. Configurable fields:
- Anthropic API key, or a gateway
base_urlwith either a Bearerauth_tokenor anx-api-key. - Default model, plus environment variables that map the opus, sonnet and haiku aliases to gateway-specific model IDs.
- MCP servers in Claude Code's
mcpServersformat, either local processes or remote HTTP servers, added alongside the servers Xcode provides. setting_sources, plus passthroughenvvariables such asHTTPS_PROXY.
Logs are written to .runtime/agent.log.
Community Discussions
Be the first to start a conversation about claude-xcode-agent
Share your experience with claude-xcode-agent, ask questions, or help others learn from your insights.
Pricing
Open Source (MIT)
MIT-licensed wrapper script that runs Claude Code as an Xcode 27 agent using your own API key or gateway. API usage costs are external.
- MIT License
- Uses your own Anthropic API key or gateway (BYOK, external cost)
- Configurable via config.json (base URL, key, model, MCP servers)
- Setup script installs node, claude and the ACP adapter
Capabilities
Key Features
- Runs Claude Code as an Xcode 27 agent over ACP
- Custom Anthropic API key or gateway base URL via config.json
- Bearer token or x-api-key gateway authentication
- Default model setting and alias mapping for gateway model IDs
- Custom MCP servers (local and remote HTTP)
- Isolates global ~/.claude/settings.json unless setting_sources opts in
- Passthrough environment variables such as HTTPS_PROXY
- One-step setup script installing node, claude and the adapter
- Logging to .runtime/agent.log
