[BUG] Bash tool fails with zsh + zoxide configuration - "__zoxide_z not found" errors

[mrwilby]

Description

The Bash tool in Claude Code consistently fails when executing commands that involve directory navigation on systems with zsh configured with zoxide (a modern cd replacement).

Environment

• OS: macOS (Darwin 24.5.0)
• Shell: zsh with zoxide configured
• Claude Code Version: 1.0.35
• Terminal: Various (tested in multiple terminals)

Error Details

When Claude attempts to execute bash commands that involve directory changes, it produces:

z:1: command not found: __zoxide_z

This error occurs even when using explicit command patterns like:
- cd system/admin-proxy && ../../sync --dry-run download
- /bin/zsh -c "cd system/admin-proxy && pwd && ../../sync --dry-run download"

Expected Behavior

Bash tool should be able to execute shell commands normally, regardless of user's shell configuration (zoxide, starship, etc.).

Actual Behavior

Commands fail with zoxide-related errors, requiring workarounds using absolute paths instead of relative navigation.

Reproduction Steps

1. Configure zsh with zoxide (common modern shell setup)
2. Use Claude Code's Bash tool to execute any command involving directory navigation
3. Observe the "__zoxide_z not found" error

Workaround

Using absolute paths instead of relative paths:

# Fails:
cd some/directory && command

# Works:
/absolute/path/to/command

Impact

This affects users with modern shell configurations (zoxide is very popular in the developer community). It forces Claude to use less efficient
absolute path workarounds and degrades the user experience.

Suggested Investigation

The issue appears to be that the Bash tool doesn't properly inherit or handle custom shell configurations/hooks that modify the shell environment. It
may be executing commands in a clean environment that lacks user-configured shell enhancements.

Additional Context

- This issue was encountered during a complex development session involving CLI tool refactoring
- The error is consistent and reproducible across different command patterns
- Absolute path workarounds are functional but less elegant and harder for Claude to reason about

[jlgeering]

other tools that hook into the shell seem to also have problems (when changing directories)

• direnv (direnv hook not run when changing directory?)
• mise-en-place (idem)

[miqsoft]

Unsure if this works with macOS but I found a simple workaround for linux zoxide users by disabling zoxide for claude only.

HowTo:

To disable zoxide initialization in environments like Claude, set the following in your settings.json:

{
  "env": {
    "DISABLE_ZOXIDE": "1"
  }
}

Then, update your .zshrc to conditionally load zoxide only if the DISABLE_ZOXIDE variable is not set:

if [ -z "$DISABLE_ZOXIDE" ]; then
    eval "$(zoxide init --cmd cd zsh)"
fi

This way, zoxide remains enabled by default but is skipped when DISABLE_ZOXIDE=1 is present in the environment.

[rwese]

Modify your loading of zoxide by testing for the ENV CLAUDECODE=1

like this:

# zoxide.zsh
# Zoxide Configuration
# This file contains zoxide-specific configuration

if command -v zoxide &>/dev/null && [[ "$CLAUDECODE" != "1" ]]; then
  eval "$(zoxide init --cmd cd zsh)"
  
  # Ensure __zoxide_z function exists
  if ! type __zoxide_z &>/dev/null; then
    function __zoxide_z() {
      if [[ "$#" -eq 0 ]]; then
        builtin cd ~
      elif [[ "$#" -eq 1 ]] && { [[ -d "$1" ]] || [[ "$1" = '-' ]] || [[ "$1" =~ ^[-+][0-9]$ ]]; }; then
        builtin cd "$1"
      else
        local result
        result="$(command zoxide query --exclude "$(pwd)" -- "$@")" && builtin cd "${result}"
      fi
    }
  fi
fi

[sebazelonka]

I have the same issue, is a bug in Claude Code or is the expected behavior? I don't see any official answer here and the solution proposed looks like a workaround till this is fixed.

[rwese]

@sebazelonka In my opinion, this appears to be a local environment issue, likely caused by shell configuration.

The workarounds or solutions suggested so far are therefore valid.

Relying on function calls that differ from the built-in behavior can be both an advantage and a disadvantage, as it allows for enhancements but may also introduce unintended issues.

One possible solution is to ensure the AI agent tool runs in a "clean" environment or with a specific, controlled shell configuration.

[kallepyorala]

Isn't it easier to just skip the zoxide init for claude

if [[ "$CLAUDECODE" != "1" ]]; then
    eval "$(zoxide init --cmd cd zsh)"
fi

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/2407
2. https://github.com/anthropics/claude-code/issues/1799
3. https://github.com/anthropics/claude-code/issues/2216

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[mrwilby]

Looks like https://github.com/anthropics/claude-code/issues/2407 should capture this issue.

[github-actions[bot]]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.