Claude Codeでzoxideなどシェル関数が使えない原因と対処法

Claude CodeのBashツールでzoxideのzコマンドを使うと、command not found: __zoxide_zのようなエラーで失敗することがあります。原因はzoxide側の不具合ではなく、Bashツールがシェル関数をセッション開始時に一度だけ捕捉する仕組みと、アンダースコアで始まる関数名を取りこぼしていた過去のバグにありました。症状の再現条件と、どのバージョンから解消しているかをまとめます。

Bashツールでzoxideの関数が見つからないという報告

この問題は2025年6月21日、Claude Code v1.0.18を使うユーザーがGitHubに報告しました。環境はWSL2上のUbuntu、シェルはzsh、zoxideは0.9.8です。~/.zshrcにeval "$(zoxide init zsh)"を書いておくと、通常のターミナルではcdの代わりにzでディレクトリ移動ができます。この初期化コードはシェル関数__zoxide_zを動的に生成する仕組みです。

ところがClaude CodeのBashツールで同じcdを実行すると、z:1: command not found: __zoxide_zというエラーになりました。通常シェルではtype __zoxide_zが関数の実体を返すのに対し、Bashツール内では同じコマンドが「見つからない」と返します。報告者は手動での関数再定義、.zshrcの再読み込み、evalの直接実行、補完キャッシュのクリア、初期化オプションの変更を試しましたが、いずれも解決しませんでした。

同じ症状は複数のユーザーから寄せられています。fishシェルとdirenvの組み合わせで似た問題を報告したコメントや、単純に「こちらでも同じ現象が起きている」という追認コメントが並びました。当時のユーザーが実際に試した回避策は次の3つです。

• SHELL=/bin/bash claudeでzshではなくbashを使わせる
• claudeコマンドをSHELL=/bin/bash付きでラップする関数を.zshrcに定義する
• zoxideの初期化を対話シェルに限定するガード([[ $- == *i* ]] && eval "$(zoxide init --cmd cd zsh)")を追加する

2025年10月には、別のユーザーが「ダブルアンダースコアで始まる関数だけが継承されていないようだ」と気づき、zoxide initの出力から__プレフィックスをsedで除去する回避策を報告しました。この観察は、後述する公式の修正内容と一致します。issue自体は30日間動きがなかったため2026年1月10日にGitHubのstaleボットが自動クローズし、1週間後にロックされています。

報告のBusiness Impact欄は、影響がzoxideだけにとどまらないとも指摘しています。starshipのプロンプトカスタマイズやfzfとの連携など、シェル関数に依存する開発生産性ツール全般が同じ理由で動かなくなるという内容です。ユーザー設定に依存するシェル関数は、ツールの種類を問わず同じ捕捉処理の対象になります。

Bashツールがシェル関数をどう扱う仕組みか

Claude Codeの公式ツールリファレンスは、Bashツールの挙動を次のように説明しています。セッション開始時に一度だけ、使用中のシェルに応じて~/.zshrc・~/.bashrc・~/.profileのいずれかをソースし、その結果生まれたエイリアス・関数・シェルオプションを捕捉して、以降のすべてのBashコマンドに適用します。

この仕組みは環境変数とは扱いが異なります。Bashツールは各コマンドを別々のプロセスとして実行するため、あるコマンドでexportした環境変数は次のコマンドに引き継がれません。仮想環境の有効化はClaude Code起動前に済ませておくのが基本です。作業ディレクトリのcdはプロジェクトディレクトリ内であれば持ち越されますが、サブエージェントのセッションでは持ち越されないという制約もあります。Bashツールにはこのほかにも、Linux/WSLでコマンドのメモリ使用量に上限をかけるCLAUDE_CODE_TOOL_MEMORY_LIMITのような、ドキュメント化された個別の挙動がいくつかあります。

Bashツールという呼び方自体も、コード実行系のほかの仕組みと混同されがちです。この点はcode executionとbashツールの混同が起きる実行環境の対処法で扱っています。

アンダースコアで始まる関数名が消えていた

公式changelogを遡ると、シェル関数の捕捉処理そのものに、アンダースコアで始まる関数名を取りこぼすバグがあったことが分かります。

zoxideの__zoxide_zはダブルアンダースコアで始まる関数名なので、v2.1.47の修正が直接該当します。issue #2407自体はstaleボットに自動クローズされていましたが、ダブルアンダースコア関数全般(changelogの例は__git_ps1)を対象にした修正がissue #25824としてv2.1.47のchangelogに記録されています。GitHubのissueが放置クローズされたことは、必ずしも問題が直らないまま残ることを意味しません。

2026年2月24日公開のv2.1.51のchangelogには「シェルスナップショットが利用できる場合、Bashツールはデフォルトでログインシェルフラグをスキップする」という記述もあり、シェル関数を事前に捕捉しておく仕組み自体はこの時点で既に存在していたことが読み取れます。

現在のバージョンでzoxideを使う設定

__zoxide_zを落としていた原因はv2.1.47で、シングルアンダースコア関数の取りこぼしはv2.1.147で、それぞれ修正されています。そのため、それ以降のバージョンではガードなしの標準的な初期化(zoxideのREADMEにあるeval "$(zoxide init zsh)")で動く前提になります。動かない場合は下の「よくあるつまずき」を確認します。

# ~/.zshrc に1行追加
eval "$(zoxide init zsh)"

.bashrcを使っている場合はzoxide init bashに置き換えます。設定を追加した直後は、Claude Codeのセッションを再起動して反映させます。個別のBashコマンドを検査・制御したい場合は、PreToolUse hookを組み合わせる選択肢もあります。

nvmのようにPATHを書き換えるだけのツールは扱いが別

zoxideは関数を生成するツールですが、nvmのようにPATHなどの環境変数だけを書き換えるツールは扱いが異なります。環境変数は自動では捕捉されないため、CLAUDE_ENV_FILEにexport文を書くか、SessionStart hookで動的に生成する必要があります。公式ドキュメントは、セットアップコマンドの前後で環境変数を比較して差分だけを書き出す方法を示しています。

#!/bin/bash
 
ENV_BEFORE=$(export -p | sort)
 
source ~/.nvm/nvm.sh
nvm use 20
 
if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi
 
exit 0

CLAUDE_ENV_FILEが使えるのはSessionStart・Setup・CwdChanged・FileChangedの4種類のhookに限られ、ほかのhookタイプからは参照できません。シェル関数の捕捉とこの仕組みは独立しているため、両方を必要とするツールチェーンでは組み合わせて使うことになります。

PowerShellツールではプロファイルが読み込まれない

同じシェル関数の話でも、WindowsのPowerShellツールでは事情が異なります。公式ドキュメントはプレビュー中の既知の制限として「PowerShellプロファイルは読み込まれない」ことを明記しています。つまり$PROFILEに定義した関数は、Bashツールの.zshrcのようには捕捉されません。

PowerShellでzoxideに相当するツール(zoxide init powershellが生成する関数など)をプロファイル経由で使っている場合、Bashツール側の修正とは独立に、この制限がそのまま当てはまります。プロファイルを読み込む代替策は公式ドキュメントに示されていません。

影響度早見表

よくあるつまずき

• 修正済みバージョンなのに直らない: claude --versionで実際のバージョンを確認します。アップデートはclaude updateです。v2.1.47未満ではダブルアンダースコアの関数、v2.1.147未満ではシングルアンダースコアの関数がまだ影響を受けます
• 想定と違うシェルが検出されている: Claude Codeは実行中のシェルの種類に応じて、zsh・bash・profileのどれをソースするかを決めます。ログインシェルをzshに変更したつもりでも、ターミナルアプリやOS側の設定が古いままで、実際にはbashが使われているケースがあります。echo $SHELLやps -p $$で実際に使われているシェルを確認します
• 関数が別ファイルからさらにsourceされている: .zshrcが別のプラグイン管理ファイルをsourceし、その中でzoxideなどを初期化している構成でも、最終的に.zshrcをソースした結果として関数が生まれる限りは捕捉の対象になります。ただし、どこまで深いsourceの連鎖に対応するかは公式ドキュメントに明記がなく、複雑な構成では動作を実機で確認する必要があります

まとめ

zoxideの__zoxide_zが見つからない症状は、zoxide自体のバグではなく、Claude CodeのBashツールがセッション開始時にシェル関数を捕捉する処理で、アンダースコア始まりの関数名を落としていたことが原因でした。ダブルアンダースコアの関数はv2.1.47で、シングルアンダースコアの関数はv2.1.147で、それぞれ修正されています。それ以降のバージョンでは、対話シェル限定のガードのような回避策を組まなくても、標準的なzoxide initの初期化コードで動く前提になります。ただし関数・エイリアスの捕捉はセッション開始時の1回きりで、設定変更後は再起動が必要な点と、PowerShellツールではプロファイル自体が読み込まれない点は、現在も変わらない制約として残っています。