headroom.walls.sh · env

Claude Code environment variables

Where to set ANTHROPIC_API_KEY, what other env vars Claude Code reads, and how to manage per-project environment without leaking secrets.

The one required variable

Claude Code needs ANTHROPIC_API_KEY to call the Anthropic API. If you installed via the Claude desktop app or Homebrew, this is set for you. If you're running claude from a fresh terminal and it asks for a key, this is what's missing.

export ANTHROPIC_API_KEY="sk-ant-..."

Where you put this depends on whether you want it globally or per-project.

Global setup — shell profile

The simplest option: add the export to your shell's startup file. This makes the key available in every terminal session on your machine.

zsh (macOS default)

# ~/.zshrc or ~/.zprofile
export ANTHROPIC_API_KEY="sk-ant-api03-..."

Then reload: source ~/.zshrc (or open a new terminal).

bash

# ~/.bashrc or ~/.bash_profile
export ANTHROPIC_API_KEY="sk-ant-api03-..."

Use ~/.bash_profile on macOS (login shells) and ~/.bashrc on Linux.

Per-project setup — direnv and .envrc

For project-specific keys or overrides — a different Anthropic account, a test key, a key with limited permissions — use direnv. It automatically loads and unloads env vars when you cd into a directory.

# Install
brew install direnv

# Add to ~/.zshrc (or ~/.bashrc)
eval "$(direnv hook zsh)"

Then in your project directory:

# .envrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

direnv allow   # run once to trust this .envrc

Add .envrc to .gitignore if it contains real keys. If you want to commit a template, create a .envrc.example with placeholder values and gitignore the real one.

All environment variables Claude Code reads

The env block in settings.json

You can also set environment variables in ~/.claude/settings.json under the env key. These are merged with your shell environment — useful for org-wide defaults in a shared config.

{
  "model": "claude-opus-4-8",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "DISABLE_AUTOUPDATER": "1"
  }
}

Don't put your API key here if this file is shared or version-controlled. Shell profile or direnv is safer for secrets.

CI and GitHub Actions

In CI, set ANTHROPIC_API_KEY as a repository secret and inject it as an environment variable in your workflow:

- name: Run Claude Code
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
  run: claude --print "review this PR for obvious bugs"

See the CI guide for the full setup including non-interactive mode and output handling.

Verifying your setup

# Check the key is set (shows only the first few chars)
echo ${ANTHROPIC_API_KEY:0:12}...

# Quick Claude Code test
claude --print "say hello" 2>&1 | head -3

If claude --print returns a response, your key is configured correctly.

The ~/.claude directory

Once Claude Code is working, the ~/.claude/ directory holds your config: settings.json for hooks and model preferences, CLAUDE.md for project instructions. The statusLineHook in settings.json is what Headroom reads to show your session and weekly usage live in the menu bar.

brew install patwalls/tap/headroom

→ settings.json reference
→ CLAUDE.md and memory
→ Claude Code in CI
→ statusLineHook setup