OpenCode and the incomplete PATH: why your tools weren't in the agent's shell

It was a Tuesday evening. I had just installedhttps://opencode.ai[OpenCode], the AI agent that promised to transform the way I code. First test: asking it to list my GitHub repositories.

Strange.`gh`worked perfectly in my terminal. I try something else:

Then:

Java, Gradle, Node,gh— everything was invisible to the agent. My terminal, however, saw everything. As if the agent and I lived in two parallel worlds.

It took me hours to understand. Hours of`echo $PATH`, de which java, of growing frustration. I eventually realized the problem wasn’t the tools — it was theshell. OpenCode, like any agent that launches subprocesses, works innon-interactiveshells. And Zsh, in those shells, simply ignores your`.zshrc`.

What follows is the full account of this diagnostic, the resolution, and the lesson I learned. If you use an AI agent — OpenCode, Aider, Cursor, or even cron scripts — this problem will affect you one day.

When you open a terminal, Zsh treats it as aninteractiveshell. It loads`.zshrc`, which initializes everything: SDKMAN, NVM, pnpm, aliases, your pretty prompt. Your environment is complete.

But when OpenCode executes a command, it doesn’t launch an interactive terminal. It launches anon-interactiveshell — a task shell, with no human behind the screen. And Zsh, in this context, skips`.zshrc`. It only reads`.zshenv`.

Why does this distinction exist? Because a non-interactive shell is designed to execute scripts, not to serve a human user. Loading aliases, prompts, and completions in a script running in the background would be a waste. The problem is that your PATH — the most critical information for finding executables — is often initialized in`.zshrc`, not in`.zshenv`.

The root of the problem:Zsh only sources .zshrc for interactive shells. OpenCode, like any AI agent that launches subprocesses, uses non-interactive shells. These shells only read`.zshenv`.

Zsh hasfour initialization files, each with a specific role. It’s an elegant design — but it’s also the heart of the problem:

The table gives a hint, but it must be understood in depth. Think of it like the rooms of a house:

The tragedy is that most of us put the PATH in the living room. And the AI agent is never allowed to enter.

The problem in a diagram:

When you open a terminal, Zsh is interactive: it reads`.zshrc`, everything works. When OpenCode launches a shell to execute a command, Zsh is non-interactive: it skips`.zshrc`, reads only`.zshenv`. Et si `.zshenv`doesn’t exist or doesn’t contain the PATH — it’s a desert.

Before fixing, you must understand exactly what is missing. Here is a reproducible diagnostic method — keep it bookmarked if you work with AI agents.

The strategy is simple, but requires precision: put in`.zshenv` onlythe essential paths, without sourcing heavy initialization scripts. We don’t move`.zshrc`into`.zshenv`— we extract the essentials.

Before moving to the pitfalls, a visual summary of the transformation. On the left, what you had (everything in`.zshrc`, invisible to the agent). On the right, what you have now (essential paths in`.zshenv`, visible everywhere).

Not everything is perfect with this approach. Here are the problems I encountered and how to bypass them.

After creating`.zshenv`and the NVM symlink, validate that everything works — in both contexts:

Both must succeed. If so, your AI agent will see the same tools as you. If not, go back to the step-by-step diagnostic — you probably forgot a path or the NVM symlink is not up to date.

_ A non-interactive shell is like a silent guest: it only reads what is posted on the front door. If the PATH is in the living room, it will never see it. _