Skip to main content
This guide provides instructions for integrating Claude Code with the Truefoundry AI Gateway.

​
What is Claude Code?

Claude Code is Anthropic’s agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster through natural language commands. It serves as an intelligent pair programming partner that can read, analyze, and work with your entire project structure.

​
Model Configuration

Claude Code supports model aliases (opus, sonnet, haiku, opusplan) that provide convenient shortcuts for different use cases. When integrating with TrueFoundry, you can configure these aliases to use your specific TrueFoundry models through environment variables.
Model aliases allow you to switch between different Claude models during your coding session using simple commands like /model opus or /model sonnet.

​
Prerequisites

Before integrating Claude Code with TrueFoundry, ensure you have:
  1. TrueFoundry Account: Create a Truefoundry account with atleast one model provider and generate a Personal Access Token by following the instructions in Generating Tokens
  2. Claude Code Installation: Install Claude Code following the official documentation
  3. Configure models in Truefoundry for each provider you want to use

​
Integrate Truefoundry with Claude Code

Claude Code uses a settings.json file for configuration. You’ll need to modify the environment variables to route requests through Truefoundry. First, get the base URL and model name from your TrueFoundry AI Gateway playground using the unified code snippet (ensure you use the same model name as written):
TrueFoundry playground showing unified code snippet with base URL and model name highlighted for Claude Code integration

Get Base URL and Model Name from Unified Code Snippet

Claude Code can be configured either globally or per project by editing the settings file:
  • Global: ~/.claude/settings.json
  • Project-specific: .claude/settings.json in your project directory
  • Anthropic Direct API
  • AWS Bedrock
  • Google Vertex AI
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://{controlPlaneUrl}/api/llm/proxy",
    "ANTHROPIC_API_KEY": "dummy", 
    "ANTHROPIC_CUSTOM_HEADERS": "Authorization: Bearer your-truefoundry-api-key\nX-TFY-LOGGING-CONFIG: {\"enabled\": true}",
    "ANTHROPIC_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-4-opus-20250514",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-3-5-haiku-20241022"
  }
}
Replace:
  • your-truefoundry-api-key with your TrueFoundry API key
  • controlPlaneUrl with your Control Plane URL
  • projectId with your Google Project Id
  • region with Region of the Model
  • Update the model name to match your configured TrueFoundry models

​
Using Claude Code VS Code Extension

The Claude Code VS Code extension works seamlessly with TrueFoundry once you’ve configured the CLI.
The VS Code extension is not standalone. It requires the Claude Code CLI to be installed separately and configured first.
Setup Steps:
  1. Install and configure the Claude Code CLI as described above
  2. Install the VS Code extension
  3. Launch VS Code from your terminal to inherit the configuration:
code .
The extension automatically uses your CLI configuration (base URL, API keys, model aliases). No separate setup needed.
Important for macOS/Linux: Launch VS Code from the terminal where you’ve set up Claude Code. GUI applications don’t inherit shell environment variables by default.

​
Model Alias Configuration

The following environment variables map Claude Code’s built-in aliases to your TrueFoundry models:
  • ANTHROPIC_DEFAULT_OPUS_MODEL: Maps opus alias to your TrueFoundry Opus model
  • ANTHROPIC_DEFAULT_SONNET_MODEL: Maps sonnet alias to your TrueFoundry Sonnet model
  • ANTHROPIC_DEFAULT_HAIKU_MODEL: Maps haiku alias to your TrueFoundry Haiku model
Benefits: Model aliases enable seamless integration with Claude Code’s built-in commands, flexible model switching with /model opus or /model sonnet, and optimized workflows by choosing the right model for each task.

​
Example Usage

# Use different models for different tasks
claude --model opus "Design a scalable microservices architecture"
claude --model sonnet "Implement a user authentication system"
claude --model haiku "Write a function to validate email addresses"

# Switch models during a session
/model opusplan  # Uses opus for planning, sonnet for execution

​
Claude Agent SDK

The Claude Agent SDK is the successor to the Claude Code SDK, providing programmatic access to build custom AI agents with the same capabilities as Claude Code.
The Claude Code SDK has been deprecated. If you’re using the old SDK, migrate to the Claude Agent SDK for continued support and new features.

​
Installation

pip install claude-agent-sdk

​
Key Changes from Claude Code SDK

What changed: The SDK no longer reads from filesystem settings automatically. You must explicitly specify which settings to load. Manual setup required: You now need to explicitly load settings for:
  • Settings files (.claude/settings.json for project, ~/.claude/settings.json for user)
  • CLAUDE.md files (project memory)
  • Custom slash commands from .claude/commands/

​
TrueFoundry Integration

Your existing .claude/settings.json configuration works seamlessly with the Agent SDK. Simply specify setting_sources=["project"] to load your TrueFoundry gateway configuration: 
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Analyze my codebase",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads .claude/settings.json
        max_turns=5,
        allowed_tools=["Read", "Grep", "Glob"]
    )
):
    if message.type == "result":
        print(message.result)
All your existing TrueFoundry configurations (Anthropic Direct, AWS Bedrock, Google Vertex AI) work identically with the Agent SDK.
⌘I