Claude Code

This guide explains how to configure Claude Code to work with the PwC AI-CoE Coding Agents Gateway.

Installation and Telemetry Setting

The installation script sets everything up in one step. It:

installs Claude Code (if it isn't already installed),
writes your ~/.claude/settings.json pointed at the gateway,
enables telemetry and gateway-side model discovery,
installs and registers the telemetry attestation hook, and
installs and registers the status line (macOS/Linux only).

Any tools the script needs are installed automatically — just download it and run it.

Already have Claude Code installed? Use the script anyway

The script below is also a telemetry setup tool, not just an installer. If Claude Code is already installed, it skips the install and simply applies the correct configuration — it writes ~/.claude/settings.json (gateway connection + telemetry), installs the telemetry attestation hook, and (macOS/Linux) installs the status line. Run it whenever you need to (re)configure telemetry, even on an existing Claude Code install.

🖥️ Download for macOS / Linux 💻 Download for Windows

macOS / Linux — run it with:

cd ~/Downloads
chmod +x install-claude.sh
./install-claude.sh

Windows — open a new PowerShell terminal and run:

cd $HOME\Downloads
./install-claude.ps1   # if prompted, press R (Run Once) to start the script

The script prompts for your API key and tenant ID — paste them without leaving any trailing spaces.

You may need to close and reopen the terminal afterwards. Check that the installation succeeded by typing in a new shell:

claude

Claude Context

Remember that Claude Code searches for files in the current working directory and subdirectories. To avoid providing too much context, open claude in the project directory.

Manual Configuration

Not mandatory

Manual configuration is not needed if you used the installation script — it automatically creates the settings file, enables telemetry, and installs the attestation hook for you.

Once installed, configure Claude Code by editing the settings file located at:

~/.claude/settings.json

Creating the Settings File

Common Issue

Many colleagues have reported that settings.json is not automatically created until you send your first message to Claude Code, which requires logging in with an Anthropic account. To bypass this, manually create the file at the path above.

Environment Variables

Add the following to your settings.json:

{
  "model": "sonnet",
  "env": {
    "ANTHROPIC_BASE_URL": "https://idi-coding-agents.pwc.it",
    "ANTHROPIC_AUTH_TOKEN": "apikey=<your-api-key>&tenantid=<your-tenant-id>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_SKIP_AUTH_LOGIN": "1",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://idi-coding-agents.pwc.it",
    "OTEL_EXPORTER_OTLP_HEADERS": "authorization=Bearer apikey=<your-api-key>&tenantid=<your-tenant-id>"
  },
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash \"$HOME/.claude/telemetry-attest-hook.sh\"" }
        ]
      }
    ]
  }
}

Windows — the hook is a native PowerShell script instead (no bash/curl/jq dependency), so the hooks block looks like this instead:

  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\\.claude\\telemetry-attest-hook.ps1\"" }
        ]
      }
    ]
  }

Replace <your-api-key> and <your-tenant-id> with the values obtained as described in Get Access.

Telemetry Settings (Required)

Why Telemetry?

Telemetry helps PwC track ROI, analyze usage patterns, and demonstrate the value of AI coding assistants across the organization. This data is essential for continued investment in these tools.

Privacy: We do not collect conversation content, code, or file names. Only aggregate usage metrics (session counts, token usage, costs) relevant for ROI calculation are collected.

Variable	Description
`CLAUDE_CODE_ENABLE_TELEMETRY`	Set to `1` to enable telemetry
`OTEL_METRICS_EXPORTER`	Set to `otlp` to use OpenTelemetry Protocol
`OTEL_LOGS_EXPORTER`	Set to `otlp` to use OpenTelemetry Protocol
`OTEL_EXPORTER_OTLP_PROTOCOL`	Required — Set to `http/protobuf` for HTTP transport
`OTEL_EXPORTER_OTLP_ENDPOINT`	Required — Must be the IDI gateway URL (`https://idi-coding-agents.pwc.it`)
`OTEL_EXPORTER_OTLP_HEADERS`	Required — Authentication header, bound to your identity (see below)

OTEL_EXPORTER_OTLP_ENDPOINT and ANTHROPIC_BASE_URL must both point at the IDI gateway (https://idi-coding-agents.pwc.it) so your telemetry reaches PwC. Pointing them elsewhere blocks requests.

OTEL_EXPORTER_OTLP_HEADERS must use the format:

authorization=Bearer apikey=<your-api-key>&tenantid=<your-tenant-id>

The apikey and tenantid must be the same ones from your ANTHROPIC_AUTH_TOKEN — the gateway verifies they match the credentials you authenticate with, so telemetry cannot be sent under a different identity.

Your PwC email, team, and department are resolved server-side from your API key, so you do not need to set OTEL_RESOURCE_ATTRIBUTES.

Configured telemetry but still getting a 403?

The 403 body lists the exact settings that are wrong (e.g. OTEL_LOGS_EXPORTER must be 'otlp' but is 'otlps'). Fix them in the env block of ~/.claude/settings.json and restart Claude Code so the SessionStart hook re-validates. If it persists:

Confirm OTEL_EXPORTER_OTLP_ENDPOINT and ANTHROPIC_BASE_URL both point at https://idi-coding-agents.pwc.it
Confirm OTEL_EXPORTER_OTLP_HEADERS uses authorization=Bearer apikey=<key>&tenantid=<id> with your key/tenant
Check you are using an API key from the Get Access page, not a personal one

The Telemetry Attestation Hook

The telemetry attestation hook runs automatically every time Claude Code starts. It checks your telemetry configuration against the gateway and, if anything is wrong, prints exactly what to fix — so you find out at startup instead of when your requests get blocked.

The installation script installs and registers this hook for you. If you are configuring manually, add the hooks.SessionStart entry shown in the Environment Variables example above, then download the hook.

macOS / Linux — to ~/.claude/:

curl -fsSL https://idi-coding-agents.pwc.it/downloads/telemetry-attest-hook.sh -o ~/.claude/telemetry-attest-hook.sh
chmod +x ~/.claude/telemetry-attest-hook.sh

Windows — to %USERPROFILE%\.claude\ (the hook is a native PowerShell script — no bash/curl/jq dependency):

Invoke-WebRequest -Uri https://idi-coding-agents.pwc.it/downloads/telemetry-attest-hook.ps1 -OutFile "$env:USERPROFILE\.claude\telemetry-attest-hook.ps1"

Restart Claude Code afterwards so the hook attests your configuration.

Troubleshooting First Launch

If Claude Code prompts for login despite a correct settings.json, the env block is not loaded during the very first startup. Export the two required variables directly in your terminal session to bypass the login screen:

export ANTHROPIC_BASE_URL="https://idi-coding-agents.pwc.it"
export ANTHROPIC_AUTH_TOKEN="apikey=<your-api-key>&tenantid=<your-tenant-id>"

Then launch Claude Code:

claude

Claude Code should start without a login prompt. Once it does, you do not need to add these exports to ~/.zshrc — the env block in settings.json takes over for all subsequent launches.

If Claude Code still prompts for login, run these diagnostic checks:

Verify settings.json is valid JSON:

python3 -m json.tool ~/.claude/settings.json

Confirm the file exists and contains the expected variables:

grep -E "ANTHROPIC_BASE_URL|ANTHROPIC_AUTH_TOKEN" ~/.claude/settings.json

Check that Claude Code can reach the gateway (requires VPN):

curl -s -o /dev/null -w "%{http_code}" https://idi-coding-agents.pwc.it/models

Expected output: 200. Any other result means VPN is not active or the endpoint is unreachable.

Core Settings

Setting	Description
`model`	Default model to use. We recommend sonnet for the best balance of performance and cost. Options: `sonnet`, `opus`, `haiku`

Variable	Description
`ANTHROPIC_BASE_URL`	Gateway endpoint URL
`ANTHROPIC_AUTH_TOKEN`	Your credentials (see Get Access)
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	Set to `1` so Claude Code discovers the models the gateway serves and uses supported default versions automatically
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	Disables update checks and other non-essential network traffic
`CLAUDE_CODE_SKIP_AUTH_LOGIN`	Skips the Anthropic login screen (the gateway handles authentication)

Model Pinning (Recommended)

Model pinning is recommended but optional. With CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY enabled, the gateway advertises the models it serves and Claude Code selects supported default versions automatically — so in most cases you do not need to set anything. Pinning is still useful if you want to lock each tier to a specific, known-supported version and avoid Claude Code defaulting to a newer version that isn't available on the PwC GenAI Shared Service yet.

Variable	Example Value	Description
`ANTHROPIC_DEFAULT_OPUS_MODEL`	`claude-opus-4-7`	Pin the Opus model version
`ANTHROPIC_DEFAULT_SONNET_MODEL`	`claude-sonnet-4-6`	Pin the Sonnet model version
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claude-haiku-4-5-20251001`	Pin the Haiku model version

The values shown above use the vendor naming convention — the same format accepted by the gateway. See the Available Models page for the full list of supported model IDs and their accepted naming formats.

Verify Configuration

After saving your settings.json, verify the configuration is working:

Open a terminal and run claude
Claude Code should start without prompting for Anthropic login
Send a test message to confirm connectivity to the gateway

If successful, you'll see responses from Claude without needing an Anthropic account.

Network Requirements

You must be connected to the PwC VPN (Italy or Italy On-Premise) to reach the gateway endpoint. See the overview page for details on available endpoints.

Model Mapping

The gateway automatically maps Claude Code's model names (e.g., sonnet, opus, haiku) to the corresponding Anthropic models available on the PwC Shared Service. With gateway-side model discovery enabled (CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY), Claude Code picks supported default versions automatically. You may still pin specific model versions if you want to lock to a known-supported version.

Usage Options

CLI (Recommended)

The configuration above works with Claude Code CLI. We recommend using modern terminals such as:

Warp - Modern terminal with AI features
Ghostty - Fast, native terminal

Using CLI allows you to add extensions that display remaining context window and budget in the status line through our utility tools.

VS Code Extension

This configuration also works with the Claude Code VS Code extension. All core features are available, though we recommend CLI for the full experience.

Additional Configuration

For all other Claude Code settings, including:

Default model selection at startup
Permissions configuration
Plugins
Default mode (plan, accept edits, etc.)

Refer to the official Claude Code documentation.

PwC Utility Tools

After setting up Claude Code, consider installing these optional tools created by the AI-CoE team:

Tool	Description
Status Line	Terminal status bar showing model, context window, costs, and remaining budget
Budget MCP Server	Query your remaining budget directly from Claude Code

See the Utility Tools section for installation instructions.

Installation and Telemetry Setting​

Manual Configuration​

Creating the Settings File​

Environment Variables​

Telemetry Settings (Required)​

The Telemetry Attestation Hook​

Troubleshooting First Launch​

Core Settings​

Model Pinning (Recommended)​

Verify Configuration​

Network Requirements​

Model Mapping​

Usage Options​

CLI (Recommended)​

VS Code Extension​

Additional Configuration​

PwC Utility Tools​