Setting Environment Variables for Your Session

Your project probably needs a few environment variables set — a mode flag, a region, a path. Rather than exporting them by hand each time, put them in the env key of settings.json. Claude Code applies them to the session automatically.

How to set them

The env key holds an object of name/value pairs. Every value is a string.

{
  "env": {
    "NODE_ENV": "development",
    "AWS_REGION": "us-east-1",
    "LOG_LEVEL": "debug"
  }
}

These become part of the environment for the session, so commands Claude runs — tests, builds, scripts — see them.

Where to put the env block

Think about who needs the variable. If the whole team needs it for the project to work, put the env block in the project file, .claude/settings.json, so it ships in git. If it's a personal value or something you're testing, put it in .claude/settings.local.json so it stays off git. Broad, everywhere-you-work defaults can live in your user file, ~/.claude/settings.json.

Remember the layering

Because settings files layer, the same variable can be set at more than one level. The higher level wins: local beats project, project beats user. So a teammate's shared project value can be quietly overridden by your own local file when you need a different value.

A word of care

The project file is checked into git, so don't put secrets there — tokens, passwords, private keys. Anyone with repo access would see them. Keep plain configuration in env, and load secrets a safer way. A later article in this series covers apiKeyHelper, which is built for exactly that.