Environment configuration

Configuration overview

Claude Code uses three levels of configuration, from the most global to the most specific:

1. The environment variable ANTHROPIC_API_KEY: your identity
2. The settings.json file: your global preferences
3. The CLAUDE.md file: context specific to each project

Each level builds on the previous one. Together, they let Claude Code understand who you are, how you work, and what you're working on.

Subscription or API key?

Before configuring anything, an important point: today, a Claude subscription (Pro or Max) is far more cost-effective than an API key for using Claude Code.

If you use a Claude subscription (Pro or Max), simply select "Claude App" during authentication, no additional configuration needed.

Configure the API key (if applicable)

If you chose to use an API key rather than a subscription, the recommended method is to set an environment variable in your shell.

# Add this line to your ~/.bashrc (bash) or ~/.zshrc (zsh)
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Reload your configuration
source ~/.bashrc  # or source ~/.zshrc

# Verify that the variable is set
echo $ANTHROPIC_API_KEY
# sk-ant-... ← You should see your key

Alternative: set the key in settings.json

You can also store your key in Claude Code's configuration file (see next section). This method is less recommended because it mixes configuration and secrets, but it works.

The settings.json file

The ~/.claude/settings.json file is Claude Code's global configuration file. It controls default behavior across your entire machine.

Location

# The file lives in your home folder
~/.claude/settings.json

# On macOS/Linux
/home/your-name/.claude/settings.json

# On Windows (WSL)
/home/your-name/.claude/settings.json

File structure

Here's a complete example with the most useful options:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(node *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

Permissions in detail

The permissions system controls what Claude Code can do without asking for confirmation.

Per-project configuration

In addition to the global ~/.claude/settings.json file, you can create a .claude/settings.json file at the root of each project. Project settings are merged with global settings (the project takes priority).

my-project/
├── .claude/
│   └── settings.json   ← Project-specific configuration
├── CLAUDE.md            ← Project context
├── src/
├── package.json
└── ...

The CLAUDE.md file

This is the most important file in your entire configuration. The CLAUDE.md file gives Claude Code persistent context about your project. It reads it automatically at every session.

Where to place it

Place the CLAUDE.md file at the root of your project (at the same level as package.json or Cargo.toml).

Recommended structure

Here's a template you can adapt to your projects:

# CLAUDE.md

## About this project
E-commerce application built with Next.js 14, TypeScript, and Prisma.
PostgreSQL database hosted on Supabase.

## Code conventions
- Functional React components only (no classes)
- File naming in kebab-case (my-component.tsx)
- Tests with Vitest, minimum coverage 80%
- Absolute imports with the @/ prefix
- Strict TypeScript, never use `any`

## Useful commands
- `npm run dev`: Development server (port 3000)
- `npm run test`: Run tests
- `npm run build`: Production build
- `npm run lint`: Check linting

## Project structure
- src/app/: Next.js pages (App Router)
- src/components/: Reusable components
- src/lib/: Utilities and configuration
- prisma/: Database schema and migrations

## Important rules
- NEVER modify files in /generated/
- Prisma migrations must always be named
- Environment variables are in .env.local (never committed)
- Deployment is done via GitHub Actions on the main branch

Hierarchical CLAUDE.md

Claude Code supports hierarchical CLAUDE.md files. This means you can place a CLAUDE.md in any subfolder. Claude Code will read all CLAUDE.md files between the project root and the current folder.

my-monorepo/
├── CLAUDE.md                    ← Global monorepo rules
├── apps/
│   ├── web/
│   │   ├── CLAUDE.md            ← Web app-specific rules
│   │   └── src/
│   └── api/
│       ├── CLAUDE.md            ← API-specific rules
│       └── src/
└── packages/
    └── shared/
        ├── CLAUDE.md            ← Shared package rules
        └── src/

What makes a good CLAUDE.md

A good CLAUDE.md is:

• Concise: get to the point, no unnecessary prose
• Structured: use headings, lists, and code blocks
• Actionable: every piece of information should help Claude Code make better decisions
• Up to date: update it when your conventions change

A bad CLAUDE.md is vague ("this project is cool") or too long (copy-pasting all the documentation). Aim for 30 to 100 lines.

Permissions and security

Claude Code is designed with security at its core. Here are the key principles.

The principle of least privilege

By default, Claude Code asks for your approval before any action that modifies your system (writing files, running commands). This is the safest behavior.

Security best practices

• Use the deny list to block dangerous commands (rm -rf, sudo, etc.)
• Keep your API key secret and never commit it
• Always review commands proposed by Claude Code before accepting them
• Use API keys with limited permissions when possible
• Enable regular rotation of your API keys

Next steps

Your environment is configured. It's time to get hands-on and create your first project with Claude Code.

• Your first project: Build a website in 5 minutes
• What is Claude Code?: Back to the fundamentals
• Back to overview: All getting started pages