Why Claude Code Can't Find Your Tools

The Surprise

AI coding assistants like Claude Code, Cline, Aider, and similar tools spawn child shell processes to run commands on your behalf. From where you sit, the terminal looks identical to the one you use every day. But the shell those tools launch is fundamentally different from the one you interact with — and that difference determines which startup files are read, which means it determines what is on your PATH.

The result is a confusing experience: tools you have used for years are suddenly invisible to the agent trying to help you. The culprit is not your installation. It is the shell startup file hierarchy.

Zsh Startup Files and When They Are Sourced

Zsh loads different configuration files depending on how it was launched. There are four main files, and they are read in this order:

| File | Login shell | Interactive shell | Non-interactive shell | |---|---|---|---| | ~/.zshenv | Yes | Yes | Yes | | ~/.zprofile | Yes | No | No | | ~/.zshrc | No | Yes | No | | ~/.zlogin | Yes | No | No |

The key column is the last one. A non-interactive, non-login shell — the kind that Claude Code spawns — sources only ~/.zshenv. Everything else is skipped entirely.

• ~/.zshenv is sourced for every zsh invocation, no matter what. It is the right place for environment variables that must be available universally: PATH, GOPATH, JAVA_HOME, and similar exports.
• ~/.zprofile is sourced for login shells (e.g., when you open a new terminal window or SSH into a machine). Homebrew places its environment setup here on Apple Silicon Macs (/opt/homebrew/bin/brew shellenv), which is why Homebrew tools can also go missing.
• ~/.zshrc is sourced only for interactive shells — sessions where you type commands. This is where most developers put everything: aliases, prompt configuration, nvm, pyenv, rbenv, completions, and — critically — PATH customizations.
• ~/.zlogin is sourced after ~/.zshrc for login shells. It is rarely used by developers directly.

What PATH a Non-Interactive Shell Actually Sees

You can observe this yourself. Run these two commands and compare the output:

On a typical macOS developer machine, the non-interactive shell might produce something like:

While your interactive shell shows something far richer:

All those extra paths — Homebrew, nvm, Go binaries — live in ~/.zshrc, ~/.zprofile, or in scripts those files source. A non-interactive shell never reads any of them.

Diagnosing the Problem

Before changing anything, confirm the symptom. Use zsh -c to simulate what Claude Code sees:

The -i flag forces an interactive shell, which sources ~/.zshrc. If zsh -c 'which gh' prints gh not found but zsh -i -c 'which gh' prints the correct path, your PATH export is in ~/.zshrc and you have confirmed the root cause.

The Fix: Move PATH Exports to ~/.zshenv

The solution is straightforward: any environment variable that must be visible to all processes — including non-interactive subshells — belongs in ~/.zshenv, not ~/.zshrc.

Open (or create) ~/.zshenv and add your PATH exports there:

For tools that inject themselves via an eval expression in ~/.zshrc — such as nvm, pyenv, or rbenv — you need to move or duplicate that initialization into ~/.zshenv as well:

Note the --no-use flag for nvm: it initializes nvm without switching to the default Node.js version, which speeds up shell startup for non-interactive contexts. Remove it if you want the default version active everywhere.

After saving ~/.zshenv, verify without restarting your terminal:

What to Keep in .zshrc vs .zshenv

Moving everything to ~/.zshenv is not the right answer. Some configuration should stay in ~/.zshrc because it only makes sense in interactive contexts or because it has side effects that slow down non-interactive shells unnecessarily.

The Broader Pattern: Any Tool That Spawns Subshells

Claude Code is not unique here. This same behavior affects any process that spawns a child shell without the -i or -l flags:

• CI/CD pipelines (GitHub Actions, GitLab CI) run commands in non-interactive shells. This is why you often see pipelines that explicitly source ~/.bashrc or set up PATH at the top of every job.
• Cron jobs run in minimal environments with almost no PATH set.
• VS Code integrated terminal tasks and launch.json configurations may use non-interactive shells depending on the operating system and configuration.
• SSH remote command execution (ssh host 'command') uses a non-interactive shell unless you pass -t to force a TTY.
• Make and other build systems that shell out to run commands.
• Docker RUN instructions in Dockerfiles.

If you have ever fixed a "works on my machine" problem by adding export PATH=... to a CI configuration or a Dockerfile, you have already solved the same class of problem. The ~/.zshenv fix is just the developer workstation equivalent.

Kanvas is here!

Discover a catalog of best practice cloud native patterns.

Try Kanvas Now!

Putting It Together: A Minimal ~/.zshenv Template

Here is a starting point for a ~/.zshenv that covers the most common developer tools on macOS. Adjust paths to match your actual installations:

With this in place, restart Claude Code (or any tool that spawns subshells) and run your verification:

All three should now resolve to their correct paths.

Summary

The "command not found" error in Claude Code and similar AI coding assistants is a shell startup file problem, not a tool installation problem. Zsh only sources ~/.zshenv for non-interactive, non-login shells. Everything most developers have placed in ~/.zshrc — including PATH exports, version manager initializations, and tool-specific environment variables — is invisible to those shells.

The fix is permanent and simple:

1. Move PATH exports and tool-specific environment variables to ~/.zshenv.
2. Verify with zsh -c 'which <tool>' before and after.
3. Keep interactive customizations (aliases, prompt, completions) in ~/.zshrc.

The same fix benefits CI pipelines, cron jobs, Makefiles, Docker builds, and any other context where commands run in a non-interactive shell environment.

Exploring AI-assisted development workflows and developer tooling? The Layer5 community is an active group of platform engineers, open source contributors, and DevOps practitioners. Join us on Slack to share what you are building and get help when you hit walls like this one. You can also follow the Layer5 blog for more practical engineering posts.