Environment Variable Planner

Why environment variables are worth planning

Environment variables are how your project reads configuration and secrets from the environment it runs in, instead of hardcoding them into source. That separation is the whole point: the same code runs in development, staging, and production, and only the variables change. The failure mode is not using them - it is using them carelessly, which is how API keys end up committed to git and leaked. The planner above helps you do it cleanly: pick the variables your app and Claude Code actually use, mark which are secret, and get a committable .env.example plus a private checklist of what must never leave your machine.

The two-file pattern is the industry norm. You keep real values in a .env file that is gitignored and never committed, and you commit a .env.example that documents every variable your project needs using placeholders instead of real values. New contributors copy the example to .env and fill in their own values. The planner generates both sides of that so the documentation and reality stay in sync.

The Claude Code variables worth knowing

• ANTHROPIC_API_KEY - your Anthropic API key, used when Claude Code or your own app calls the API directly. This is a secret. It should live only in .env or your machine's environment, never in a committed file.
• ANTHROPIC_MODEL - overrides the default model Claude Code uses. Not secret; it is just a model identifier.
• ANTHROPIC_SMALL_FAST_MODEL - the lightweight model Claude Code reaches for on cheap background work. Not secret.
• ANTHROPIC_BASE_URL - points Claude Code at a custom API base, such as a proxy or gateway. Not secret by itself.
• DISABLE_TELEMETRY and DISABLE_ERROR_REPORTING - set to 1 to opt out of usage telemetry and automatic error reporting respectively.

Secret vs non-secret, and why it matters

The single most important distinction the planner enforces is which variables are secrets. A secret is any value that grants access or spend - an API key, a database URL with a password, a payment provider's secret key. These must never appear in a committed file, which is why the .env.example the planner writes leaves secret values blank and adds a warning comment next to each. Non-secret configuration - the port, the environment name, the log level, a model identifier - can safely carry a real default value in the example, because there is nothing to leak. Getting this split right is most of what keeps keys out of git.

The .env and .env.example workflow

1. Add .env to your .gitignore before you create it, so a real secret can never be committed by accident.
2. Create .env with your real values. This file stays on your machine and out of version control.
3. Commit the .env.example the planner generates. It documents every variable with a comment and a safe placeholder.
4. When a teammate clones the repo, they copy .env.example to .env and fill in their own values.
5. When you add a new variable, add it to both files - the real value in .env, the documented placeholder in .env.example - so the example never drifts out of date.

How to load the variables at runtime

There are a few common ways to get variables from a .env file into your running process. Many frameworks load .env automatically. In Node projects a small loader library reads the file into the process environment at startup. For a quick manual shell session you can export the variables directly, which is what the export block the planner generates is for - though for anything real, a gitignored .env is safer than pasting secrets into your shell history. Whatever the mechanism, the code reads from the environment, so it never needs to know where the values came from.

Common mistakes this prevents

The classic disasters are all avoidable. Committing a real .env is the most common - the fix is gitignoring it before it exists. Putting a secret's real value in .env.example defeats the purpose and leaks it just as surely; the planner blanks those for you. Exposing a server-side secret to the browser is another - anything a client can read is public, so a secret key must stay server-side. And letting .env.example rot until it no longer matches what the app needs makes onboarding painful; keeping the two files in lockstep as you add variables keeps the example trustworthy. If a secret ever does get committed, rotating the key is the only real fix - removing it from the latest commit is not enough, because it lives in git history.

Keeping environments separate

Development, staging, and production should use different values for the same variables - different databases, different keys, ideally different everything that touches real users or money. The variable names stay the same across environments; only the values differ, which is exactly why environment variables exist. In practice that means your production secrets live in your host's secret manager or deployment environment, not in a file on anyone's laptop, and your local .env holds development values that cannot touch production. The planner's job ends at documenting the shape; where each environment's real values live is a deployment decision, and secrets should always sit behind proper access controls.