~iany/ Environment Variables

Fix Claude Desktop PATH with CLAUDE_ENV_FILE

me@iany.me (Ian Yang) — Wed, 01 Jul 2026 21:27:36 +0800

Claude Code runs tools and shell commands on your behalf. Launched from a terminal, the CLI inherits your shell environment and everything just works. But under Claude Desktop, Claude Code is spawned from a GUI/desktop session that never sourced your interactive shell config—so if you rely on version managers like mise, asdf, or nix, the tools they install may not be on Claude’s PATH. The fix is a single setting: CLAUDE_ENV_FILE.

How it works

Set CLAUDE_ENV_FILE in .claude/settings.local.json to point at a shell file. Claude sources it before running any command.

{
"env": {
"CLAUDE_ENV_FILE": ".claude/mise.env"
}
}

That file is a plain shell snippet—export statements, one per line:

export PATH="/home/ian/.local/share/mise/shims:/home/ian/project/node_modules/.bin:$PATH"
export DATABASE_URL="postgres://localhost/db"

The path can be relative—it’s resolved from the project root—so .claude/mise.env works on any machine and can be committed alongside the project. Write both, and the next Claude session picks up everything.

Why not just put PATH in settings.json?

You can set env.PATH directly in settings.local.json, but there’s a catch: Claude does not support variable substitution like ${env:PATH}. You’d have to hardcode the full PATH, which breaks the moment dependencies change or you move between machines.

With CLAUDE_ENV_FILE you get full shell semantics—$PATH expands at runtime, conditionals work, and subshells are fair game.

Why shell init doesn’t help either: the snapshot

There’s a deeper reason the obvious fixes fail. At session start, Claude Code freezes a shell snapshot to ~/.claude/shell-snapshots/snapshot-zsh-*.sh, and the Bash tool sources that file before every command it runs.

The snapshot’s final line is export PATH=<frozen value>, and that value is Claude Code’s own process PATH captured at startup—not re-derived from your shell config. (You can spot it: it contains directories no rc file adds, like Claude’s own plugin and session bin paths.) Because this export PATH is the last thing sourced before each command, it clobbers anything your shell init did:

mise activate in .zshenv/.zshrc runs, prepends the shims—then the snapshot’s trailing export PATH overwrites it, burying the shims back where they started.
Even setting env.PATH in settings.json as a plain subprocess variable loses, because the snapshot is sourced after the process environment is set up.

CLAUDE_ENV_FILE wins because it’s sourced after the snapshot. Its export PATH="…/shims:$PATH" is the last word, so the shims land first for every Bash tool call. That’s the whole trick: it’s not just convenient shell semantics—it’s the one hook that runs late enough to survive the snapshot.

Generating the env file automatically

Writing the env file by hand gets tedious. If you use mise, you can generate both files with a task—I vibe-coded preset-claude.js for exactly this (it’s a custom mise task, not a built-in). It:

Reads env._.path from mise.toml (so per-project node_modules/.bin directories land on PATH).
Expands {{config_root}} to absolute paths.
Writes .claude/mise.env with shims, extra paths, and all mise env vars.
Sets CLAUDE_ENV_FILE in .claude/settings.local.json.

mise run preset:claude

One command, and Claude sees the exact same tools you do.

What about other version managers?

The pattern works for anything that can write a shell env file:

asdf: asdf direnv envrc > .claude/asdf.env
nix: nix print-dev-env | grep ^export > .claude/nix.env
direnv: direnv export json | jq -r 'to_entries[] | "export \(.key)=\"\(.value)\""' > .claude/direnv.env

Then point CLAUDE_ENV_FILE at it and you’re set.

Caveats

The file is sourced, not executed—shebang lines are ignored.
Changes to settings.local.json take effect on the next Claude session.
If CLAUDE_ENV_FILE is a relative path, it’s resolved from the project root.

A small config file saves you from fighting invisible PATH issues. Set it once, and Claude runs the same tools you do.

Envrc Alternative for PowerShell in Windows

me@iany.me (Ian Yang) — Sat, 06 Apr 2024 08:55:34 +0800

This post introduces a solution for automatically setting up and tearing down shell environments for PowerShell in Windows. It is proposed as a potential alternative to the bash-based tool direnv, which, while effective at loading .envrc files in the current or nearest ancestor directory, has limited compatibility with PowerShell in Windows.

.envrc.ps1

The basic idea is creating a file .envrc.ps1 with two entries: setup and teardown. The setup entry is responsible for setting up the environment up entering the directory, and the teardown entry is used when leaving it.

PowerShell allows code to be executed from a file using the dot command. This means that the entire file can be used as the setup entry. For the teardown entry, a function can be defined within the same file, and I use the function name down.

The layout of the file .envrc.ps1 looks like:

# setup
$env:GH_TOKEN = "secret"
# teardown
function global:down {
$env:GH_TOKEN = ""
}

The global: scope before the function name is necessary when this file is loaded in the hook, as I will do later.

The corresponding commands for setup and teardown entries:

Setup: . .envrc.ps1
Teardown: down

Hook

To hook the setup and teardown entries, I reference this example.

using namespace System;
using namespace System.Management.Automation;
$hook = [EventHandler[LocationChangedEventArgs]] {
param([object] $source, [LocationChangedEventArgs] $eventArgs)
end {
# 1. `down` for $eventArgs.OldPath
# 2. `. .envrc.ps1` for $eventArgs.NewPath
}
};
$currentAction = $ExecutionContext.SessionState.InvokeCommand.LocationChangedAction;
if ($currentAction) {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = [Delegate]::Combine($currentAction, $hook);
} else {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = $hook;
};

To run the code snippet, PowerShell 7 or later is required. You can install it from the repository.

Here is the algorithm for identifying setup and teardown entries:

Find the nearest .envrc.ps1 for the old path.
Find the nearest .envrc.ps1 for the new path.
If the two paths are the same, skip the next step.
If they differ, invoke the down function and remove it if it exists. Then, if found, load the .envrc.ps1 file for the new path.

The full code example to be added into PowerShell $PROFILE file.

using namespace System;
using namespace System.Management.Automation;
# existing PowerShell profile contents
# skip when version is less than 7
if ($PSVersionTable.PSVersion.Major -lt 7) {
return
}
# find the .envrc.ps1 in the currenct directory or the nearest ancestor directory.
function Find-NearestEnvrc {
param (
[Parameter(Mandatory=$true)]
[string]$StartDir
)
$currentDir = Resolve-Path $StartDir
while ($currentDir -ne "") {
$envrcPath = Join-Path $currentDir ".envrc.ps1"
if (Test-Path $envrcPath) {
return $envrcPath
}
$currentDir = Split-Path $currentDir -Parent
}
return ""
}
# hook the setup and teardown entries
$hook = [EventHandler[LocationChangedEventArgs]] {
param([object] $source, [LocationChangedEventArgs] $eventArgs)
end {
$oldEnvrc = Find-NearestEnvrc $eventArgs.OldPath
$newEnvrc = Find-NearestEnvrc $eventArgs.NewPath
if ($oldEnvrc -ne $newEnvrc) {
Get-Command down -ErrorAction SilentlyContinu
if (Get-Command down -ErrorAction SilentlyContinu) {
down
Remove-Item Function:down
}
if ($newEnvrc -ne "") {
. $newEnvrc
}
}
}
};
$currentAction = $ExecutionContext.SessionState.InvokeCommand.LocationChangedAction;
if ($currentAction) {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = [Delegate]::Combine($currentAction, $hook);
} else {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = $hook;
};

Example Usage

# setup
# set environment variable
$env:GH_TOKEN = "secret"
# load python virtual env
. .venv\Scripts\Activate.ps1
# add a helper function
function global:build {
cargo build
}
# teardown
function global:down {
# unset environment variable
$env:GH_TOKEN = ""
# unload python virtual env
deactivate
# remove the helper function
Remove-Item Function:build
}