8.4 Environment Variables

Course: Claude Code - Power User Section: Configuration Video Length: 3-5 minutes Presenter: Daniel Treasure

Opening Hook

Environment variables are the hidden control panel. Eighty-plus tuning knobs for authentication, timeouts, thinking tokens, and tool behavior. This is where power users live.

Key Talking Points

1. Why Environment Variables?

Keep config outside of code
Different values for different environments (dev, CI/CD, production)
Sensitive data (API keys) stay off disk
Can be set in shell profiles, .env files, or CI systems
Overridden easily without changing code

What to say: "Environment variables are the professional way to configure software. You don't hardcode secrets or config—you wire them up at runtime."

What to show on screen: Show the three ways to set env vars: 1. Shell profile: export VAR=value in ~/.bashrc 2. .env file: (show example, explain it's not checked in) 3. CI/CD system: (show GitHub Actions or similar setting secrets)

2. Core Authentication Variables

ANTHROPIC_API_KEY: Your API key (required for Claude Code)
ANTHROPIC_MODEL: Override the default model globally
How to set: export ANTHROPIC_API_KEY=sk-...
Never commit API keys to git
Use local settings or shell profiles instead

What to say: "Your API key is your passport. Keep it private. Set it once in your shell, not in every project."

What to show on screen: Explain the difference: - Good: Set in ~/.bashrc, never appears in git - Bad: Hardcoded in settings.json, committed to repo - Also bad: Stored as GitHub secret without protection

3. Critical Thinking and Token Variables

MAX_THINKING_TOKENS: How many tokens Claude can "think" (reason) before responding
Higher = more reasoning capability
Example: 5000 for quick tasks, 50000 for complex problems
CLAUDE_CODE_MAX_OUTPUT_TOKENS: Max output size (default 32000, max 64000)
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: Control when output is auto-compressed
These directly impact quality and cost

What to say: "Thinking tokens are your AI's scratch pad. More thinking = better answers for hard problems. But it costs more and takes longer."

What to show on screen: Show actual impact: - Task 1: Default thinking (fast, basic solution) - Task 2: High thinking tokens (slower, sophisticated solution) - Explain the trade-off

4. Timeout and Resource Variables

BASH_DEFAULT_TIMEOUT_MS: How long bash commands can run (milliseconds)
Default: reasonable but may be too short for long builds
Example: 300000 = 5 minutes
MCP_TIMEOUT: Timeout for Model Context Protocol calls
MAX_MCP_OUTPUT_TOKENS: Limit output from MCP tools
These prevent runaway processes

What to say: "Timeouts protect you. If a command hangs, it gets killed. But sometimes you need longer—adjust if you're running slow tasks."

What to show on screen: Demonstrate timeout in action: - Run a long-running command with default timeout (gets killed) - Increase BASH_DEFAULT_TIMEOUT_MS and run again (succeeds)

5. Tool-Specific Variables

Feature flags for different tool behaviors
Examples might include:
API endpoint overrides (for testing or enterprise)
MCP tool configuration
Webhook settings
Logging verbosity
Check documentation for your tools

What to say: "Most tools have knobs. They're not usually needed, but when you need them, you'll be glad they exist."

What to show on screen: Show a few examples from the 80+ variables, explain 3-4 of them

6. Setting Variables: The Three Approaches

Shell profile (~/.bashrc, ~/.zshrc): Persistent across sessions, applies everywhere
.env file: Local to project, easy to change, needs to be loaded (source .env)
settings.json env section: Claude Code specific, checked in or local
CI/CD environment: Set via system (GitHub Actions, GitLab, etc.)

What to say: "Choose the right approach for your use case. Global defaults in your shell, project-specific in .env, sensitive stuff in CI secrets."

What to show on screen: Show examples of each: 1. ~/.bashrc: export ANTHROPIC_API_KEY=sk-... 2. .env.local: MAX_THINKING_TOKENS=50000 (add to .gitignore) 3. settings.json env section:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

Demo Plan

Check current environment (45 sec)
Run env | grep ANTHROPIC to show which vars are set
Run env | grep CLAUDE to show Claude-specific vars
Explain which ones matter most
Set an environment variable for a single task (1 min)
Run: MAX_THINKING_TOKENS=50000 claude code "solve this hard problem"
Run the same prompt without the var
Show the difference in reasoning depth and response time
Configure in shell profile (1 min)
Show ~/.bashrc or ~/.zshrc
Add an export for a commonly-used var
Reload shell and verify it's set
Explain persistence
Use .env file in a project (1 min)
Create .env.local with project-specific vars
Show .gitignore entry to protect secrets
Run source .env.local and verify vars load
Explain the workflow
Configure in settings.json (45 sec)
Show how to set env vars in the env section of settings.json
Explain the scope (applies to that settings layer)
Give example: BASH_DEFAULT_TIMEOUT_MS for a slow build
Preview next video (30 sec)
"Sandbox mode is your safety bubble. Let's lock down what Claude Code can access."

Code Examples & Commands

Check what environment variables are currently set:

env | grep -i anthropic
env | grep -i claude

Set a variable for a single command:

MAX_THINKING_TOKENS=50000 claude code "complex problem"
ANTHROPIC_MODEL=claude-3-5-haiku-20241022 claude code "quick task"
BASH_DEFAULT_TIMEOUT_MS=600000 claude code "long build"

Set variables in ~/.bashrc (macOS) or ~/.bashrc (Linux):

# Add these lines to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"
export MAX_THINKING_TOKENS=30000
export BASH_DEFAULT_TIMEOUT_MS=300000

Reload shell profile:

source ~/.bashrc
# or on macOS:
source ~/.zshrc

Create and use a .env.local file:

# Create .env.local in project root
cat > .env.local << 'ENVFILE'
ANTHROPIC_API_KEY=sk-ant-...
MAX_THINKING_TOKENS=50000
BASH_DEFAULT_TIMEOUT_MS=300000
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
ENVFILE

# Load the variables
source .env.local

# Verify
env | grep MAX_THINKING

Add to .gitignore to protect secrets:

# .gitignore
.env
.env.local
.env.*.local

Configure environment variables in settings.json:

{
  "model": "balanced",
  "env": {
    "MAX_THINKING_TOKENS": "30000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000"
  }
}

Example project .env.local for a monorepo:

# API keys and auth
ANTHROPIC_API_KEY=sk-ant-...
CUSTOM_API_KEY=api-...

# Performance tuning
MAX_THINKING_TOKENS=30000
BASH_DEFAULT_TIMEOUT_MS=600000

# Tool configuration
MCP_TIMEOUT=30000
MAX_MCP_OUTPUT_TOKENS=50000

# Feature flags
DEBUG_MODE=true
VERBOSE_LOGGING=false

Common variable reference:

# Authentication (required)
ANTHROPIC_API_KEY=sk-ant-...

# Model and reasoning
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
MAX_THINKING_TOKENS=30000

# Output and token limits
CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000  # max 64000
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75

# Timeouts (in milliseconds)
BASH_DEFAULT_TIMEOUT_MS=120000
MCP_TIMEOUT=30000

# Tool limits
MAX_MCP_OUTPUT_TOKENS=50000

Gotchas & Tips

API key is required: Without ANTHROPIC_API_KEY, Claude Code won't work.
Secrets in settings.json are risky: If you check in settings.json with API keys, you've exposed your credentials. Use .env.local or shell profiles instead.
source .env is manual: Unlike some tools, Claude Code doesn't auto-load .env. You need to source .env.local in your shell.
Timing matters: Some variables (like timeouts) take effect immediately. Others (like model) might need a new session.
Case sensitivity: Variable names are case-sensitive. ANTHROPIC_MODEL is different from anthropic_model.
Override precedence: CLI flag > env var > settings.json > default. Env vars are powerful but can be confusing if multiple sources are setting them.
Thinking tokens vs max tokens: MAX_THINKING_TOKENS is for reasoning. CLAUDE_CODE_MAX_OUTPUT_TOKENS is for the final response. Both matter for quality.

Lead-out

Environment variables are the professional's control panel. You've got eighty-plus options to fine-tune Claude Code for your exact situation. The last video covers sandbox mode—your final safety mechanism.

Reference URLs

Claude Code environment variables documentation: https://claude.ai/docs/claude-code/environment-variables
Anthropic API documentation: https://anthropic.com/docs
Common .env patterns: https://github.com/motdotla/dotenv

Prep Reading

Review the ANTHROPIC_API_KEY setup process
Understand environment variable basics (how to set them, scope, persistence)
Know the difference between shell profiles, .env files, and CI systems
Identify which variables matter most for your workflow
Think about sensitive data handling (API keys, tokens, credentials)

Notes for Daniel: This is the deep-dive for people who want to optimize. Don't overwhelm with all 80+ variables—focus on the 10-15 that matter. The API key setup is critical; make sure it's crystal clear. Demo the thinking tokens impact in real-time if you can—that "more reasoning = better answer" moment is powerful. Keep the tone: "These are the knobs power users turn."

Quick Reference