Blog: Why claude code can't find your tools

Signed-off-by: Yi Nuo <218099172+yi-nuo426@users.noreply.github.com>

Author: yi-nuo426

src/collections/blog/2026/03-09-why-claude-code-cant-find-your-tools/claude-code-shell-path.png

@@ -0,0 +1,326 @@
+---
+title: "Why Claude Code Can't Find Your Tools"
+subtitle: "Understanding non-interactive shells and the .zshenv fix"
+date: 2026-03-09 10:00:00 -0530
+author: Layer5 Team
+thumbnail: ./claude-code-shell-path.png
+darkthumbnail: ./claude-code-shell-path.png
+description: "Claude Code runs in a non-interactive shell that never sources .zshrc. Learn why tools vanish and how moving PATH exports to .zshenv fixes it for good."
+type: Blog
+category: Engineering
+tags:
+  - Engineering
+  - ai
+  - Open Source
+featured: false
+published: true
+resource: true
+---
+
+{/* TODO: Add thumbnail image at ./claude-code-shell-path.png */}
+
+import { BlogWrapper } from "../../Blog.style.js";
+import { Link } from "gatsby";
+import Blockquote from "../../../../reusecore/Blockquote";
+import CTA_FullWidth from "../../../../components/Call-To-Actions/CTA_FullWidth";
+import CTAImg from "../../../../assets/images/layer5/5 icon/png/light/5-light-no-trim.webp";
+
+<BlogWrapper>
+
+<div class="intro">
+  <p>
+    You type <code>gh pr list</code> in your terminal and it works perfectly. You ask Claude Code to
+    do the same, and it replies: <em>"command not found: gh"</em>. Your Go toolchain, nvm, pyenv,
+    Homebrew binaries — all invisible to the agent. This is not a bug in Claude Code. It is a
+    fundamental property of how Unix shells start up, and once you understand it, the fix is a
+    one-time five-minute change.
+  </p>
+</div>
+
+## 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.
+
+<Blockquote
+  quote="A non-interactive, non-login shell sources only ~/.zshenv. Everything in ~/.zshrc is invisible to it — including every PATH export most developers have ever written."
+  person="Zsh Documentation"
+  title="Shell Startup File Hierarchy"
+/>
+
+## What PATH a Non-Interactive Shell Actually Sees
+
+You can observe this yourself. Run these two commands and compare the output:
+
+```bash
+# What a non-interactive shell sees
+zsh -c 'echo $PATH'
+
+# What your interactive shell sees
+echo $PATH
+```
+
+On a typical macOS developer machine, the non-interactive shell might produce something like:
+
+```
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+While your interactive shell shows something far richer:
+
+```
+/opt/homebrew/bin:/opt/homebrew/sbin:/Users/you/.nvm/versions/node/v20.11.0/bin:
+/Users/you/go/bin:/Users/you/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+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:
+
+```bash
+# Does Claude Code's shell see the tool?
+zsh -c 'which gh'
+zsh -c 'which go'
+zsh -c 'which node'
+
+# Does your interactive shell see it?
+zsh -i -c 'which gh'
+zsh -i -c 'which go'
+zsh -i -c 'which node'
+```
+
+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.
+
+<div class="note">
+  <strong>Quick diagnosis:</strong> Run <code>zsh -c 'which gh'</code> (no <code>-i</code> flag).
+  If this fails but <code>which gh</code> in your normal terminal works, your PATH is only set in
+  <code>~/.zshrc</code>. Move the relevant exports to <code>~/.zshenv</code> to fix it.
+</div>
+
+## 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:
+
+```bash
+# ~/.zshenv
+# Sourced for every zsh invocation — interactive, login, and non-interactive alike
+
+# Homebrew (Apple Silicon)
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
+
+# Go
+export GOPATH="$HOME/go"
+export PATH="$GOPATH/bin:$PATH"
+
+# Local binaries
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+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:
+
+```bash
+# ~/.zshenv — nvm initialization for non-interactive shells
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && source "$NVM_DIR/nvm.sh" --no-use
+
+# pyenv
+export PYENV_ROOT="$HOME/.pyenv"
+export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init --path)"
+```
+
+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:
+
+```bash
+# Reload .zshenv in your current shell
+source ~/.zshenv
+
+# Confirm Claude Code's shell type now finds the tool
+zsh -c 'which gh'
+zsh -c 'which go'
+zsh -c 'which node'
+```
+
+## 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.
+
+<div class="tip">
+  <strong>Guiding principle:</strong> If it is an environment variable that a program needs to
+  find another program, it belongs in <code>~/.zshenv</code>. If it is a user-facing customization
+  for your interactive terminal experience, it belongs in <code>~/.zshrc</code>.
+
+  **Keep in `~/.zshenv`:**
+  - `PATH` exports and modifications
+  - `GOPATH`, `JAVA_HOME`, `PYTHONPATH`, `CARGO_HOME`, and similar tool-specific env vars
+  - `NVM_DIR`, `PYENV_ROOT`, `RBENV_ROOT` and their `PATH` injections
+  - `EDITOR`, `PAGER`, `LANG`, `LC_ALL`
+
+  **Keep in `~/.zshrc`:**
+  - Shell aliases (`alias ll='ls -la'`)
+  - Prompt configuration (Starship, Powerlevel10k, oh-my-zsh)
+  - Tab completion setup
+  - Shell functions for interactive use
+  - History settings
+  - `zsh` plugins and plugin managers
+  - Anything that prints output (welcome messages, `neofetch`, etc.)
+</div>
+
+## 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.
+
+<Blockquote
+  quote="If a command works in your terminal but fails in a script, a CI job, or an AI agent, the first question to ask is: which startup files does this shell read?"
+  person="Platform Engineering"
+  title="Debugging Shell Environment Issues"
+/>
+
+## 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:
+
+```bash
+# ~/.zshenv
+# Sourced for ALL zsh shells — interactive, login, and non-interactive.
+# Keep this file fast and free of output-producing commands.
+
+# Homebrew (Apple Silicon Mac — change to /usr/local for Intel)
+if [[ -x /opt/homebrew/bin/brew ]]; then
+  eval "$(/opt/homebrew/bin/brew shellenv)"
+fi
+
+# Go
+export GOPATH="$HOME/go"
+export PATH="$GOPATH/bin:$PATH"
+
+# Rust / Cargo
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# Local user binaries
+export PATH="$HOME/.local/bin:$PATH"
+
+# nvm (initialize without switching to default version)
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && source "$NVM_DIR/nvm.sh" --no-use
+
+# pyenv
+if command -v pyenv &>/dev/null || [[ -d "$HOME/.pyenv" ]]; then
+  export PYENV_ROOT="$HOME/.pyenv"
+  export PATH="$PYENV_ROOT/bin:$PATH"
+  eval "$(pyenv init --path)"
+fi
+
+# Editor and locale
+export EDITOR="vim"
+export LANG="en_US.UTF-8"
+export LC_ALL="en_US.UTF-8"
+```
+
+With this in place, restart Claude Code (or any tool that spawns subshells) and run your
+verification:
+
+```bash
+zsh -c 'which gh && which go && which node'
+```
+
+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 <Link to="/community">Layer5 community</Link> is an active group of platform engineers, open source contributors, and DevOps practitioners. Join us on [Slack](https://slack.layer5.io) to share what you are building and get help when you hit walls like this one. You can also follow the <Link to="/blog">Layer5 blog</Link> for more practical engineering posts.*
+
+<CTA_FullWidth
+  image={CTAImg}
+  heading="Join the Layer5 Community"
+  alt="Layer5 Community"
+  content="Connect with platform engineers, DevOps practitioners, and open source contributors who are building the future of cloud native infrastructure."
+  button_text="Join the Community"
+  url="/community"
+  external_link={false}
+/>
+
+</BlogWrapper>