Antigravity のエージェントが node や python を『command not found』にするときの原因と対処

自分のターミナルで node -v と打てば普通にバージョンが返ってくるのに、Antigravity のエージェントに「テストを実行して」と頼むと node: command not found で止まる。python、pnpm、bun、gh ——どれも同じように「無い」と言われる。最初にこれに出くわしたとき、私は「インストールが壊れたのかな」と疑って再インストールまでしてしまいました。ですが原因はインストールではなく、エージェントが立ち上げるシェルと、あなたが普段叩いているシェルとで、参照している PATH が違うことにあります。

このすれ違いは仕組みを一度理解すると、ほとんど一発で直ります。順番に見ていきましょう。

まず症状を切り分ける

エージェントのターミナルで、次の2行を実行させてみてください。

echo $PATH
which node || echo "node not on PATH"

ここで表示される PATH が、あなたが普段使っているターミナルでの echo $PATH の結果より明らかに短い（/usr/local/bin や ~/.nvm/... が入っていない）はずです。これが確認できれば、原因は PATH 継承の問題でほぼ確定です。逆に PATH には入っているのに動かない場合は、権限やシンボリックリンク切れなど別の問題なので、この記事の範囲外になります。

切り分けをもう一段細かくしたいときは、シェルの起動モードそのものを訊いてみるのも有効です。エージェントに次を実行させると、対話シェルかどうかが一目で分かります。

case $- in *i*) echo "interactive";; *) echo "NON-interactive";; esac

NON-interactive と返ってきたら、これから説明する PATH 継承の問題に当てはまっています。

なぜエージェントだけ PATH が短いのか

鍵は「シェルがどのモードで起動したか」です。普段あなたがターミナルを開くとき、シェルは対話的ログインシェルとして起動し、~/.zshrc や ~/.bash_profile を読み込みます。nvm・pyenv・asdf・rbenv といったバージョン管理ツールは、この初期化ファイルの中で PATH を書き換えることで node や python を使えるようにしています。

一方、エージェントがコマンドを実行するとき立ち上げるシェルは、多くの場合非対話・非ログインです。さらに ~/.zshrc の冒頭には、こんなガードが書かれていることがよくあります。

# .zshrc の先頭でよく見かけるパターン
[[ $- == *i* ]] || return   # 対話シェルでなければここで打ち切る

この一行があると、非対話シェルでは nvm の初期化（source ~/.nvm/nvm.sh）まで到達せず、PATH に node が追加されないまま終わります。結果として、あなたには見えている node が、エージェントには見えないのです。

参考までに、zsh がどのモードでどのファイルを読むかを整理しておきます。置き場所を選ぶときの地図になります。

~/.zshenv — 対話・非対話・ログインを問わず、毎回いちばん最初に読まれる
~/.zprofile — ログインシェルのときだけ読まれる
~/.zshrc — 対話シェルのときだけ読まれる
~/.zlogin — ログインシェルのときだけ、~/.zshrc の後に読まれる

エージェントのシェルが拾ってくれるのは、このうち実質 ~/.zshenv だけ、という状況が多いわけです。

解決策1: PATH 設定を読み込まれる場所へ移す

最も確実なのは、バージョン管理ツールの初期化を「対話シェルかどうかに関わらず読まれる場所」に置くことです。zsh なら ~/.zshenv、bash なら ~/.profile が候補になります。たとえば nvm を使っているなら、~/.zshrc に書いていた以下のブロックを ~/.zshenv 側へ移します。

# ~/.zshenv （対話・非対話を問わず読み込まれる）
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

pyenv の場合も同様に、PATH への追加と eval "$(pyenv init -)" を ~/.zshenv に置くと、エージェントのシェルでも pyenv が効くようになります。Homebrew (Apple Silicon) で /opt/homebrew/bin が見えていないだけなら、次の一行を ~/.zshenv に足すだけで解決することも多いです。

export PATH="/opt/homebrew/bin:$PATH"

ひとつ注意したいのは、~/.zshenv は macOS のシステムが /etc/paths 経由で組み立てる PATH より前に評価される点です。PATH="...:$PATH" のように既存の $PATH を必ず後ろに残す書き方にしておけば、システム標準の /usr/bin などを上書きで消してしまう事故を避けられます。重い処理（eval を何度も呼ぶ初期化など）を ~/.zshenv に詰め込みすぎると、コマンド実行のたびに走って遅くなるので、PATH に関わる最小限だけを移すのがコツです。

解決策2: エディタ側で環境変数を渡す

シェルの初期化ファイルを触りたくない場合は、Antigravity（VS Code 系の設定構造を踏襲しています）の設定で、エージェントのターミナルに環境変数を明示的に渡せます。settings.json に次のように追記します。

{
  // 統合ターミナルにログインシェルの環境を引き継がせる
  "terminal.integrated.inheritEnv": true,
  // 不足する PATH を明示的に補う（OS に応じて osx / linux / windows を使い分け）
  "terminal.integrated.env.osx": {
    "PATH": "${env:HOME}/.nvm/versions/node/v22.11.0/bin:/opt/homebrew/bin:${env:PATH}"
  }
}

inheritEnv を true にしてもエージェントのサブプロセスまで届かないケースがあるため、確実を期すなら上のように env.osx で実際のパスを足すのが堅実です。node のパスはバージョンを上げるたびに変わる点に注意してください。固定バージョンを書くより、解決策1で nvm 自体を読み込ませるほうが保守は楽になります。

解決策3: nvm の「default」エイリアスを設定する

nvm を ~/.zshenv から読み込めるようにしても、「どのバージョンを使うか」が決まっていないと node は有効になりません。non-interactive シェルでは nvm use が走らないためです。次のコマンドで既定バージョンを固定しておきます。

nvm alias default 22   # 起動時に自動で v22 系を選ぶ

プロジェクトごとにバージョンを変えたいときは、リポジトリ直下に .nvmrc（中身は 22 など）を置いておくと、エージェントに nvm use を一手挟ませる運用もしやすくなります。

解決策4: AGENTS.md に実行手順を明示する

ここまでで環境は整いますが、もう一段の保険として、リポジトリの AGENTS.md にコマンドの前提を書いておくとエージェントの試行錯誤が減ります。

## 開発コマンド
- パッケージマネージャは pnpm を使う（npm / yarn は使わない）
- テスト実行: `pnpm test`
- 型チェック: `pnpm typecheck`
- node のバージョンは .nvmrc に従う（v22 系）

私自身、個人開発で長く保守しているアプリのリポジトリにこの数行を足してから、エージェントが npm と pnpm を取り違えて lockfile を二重生成する事故が目に見えて減りました。環境の修正とドキュメントの明示は、片方だけでなく両方やる価値があります。AGENTS.md はエージェントが毎回読んでくれる前提条件なので、「使ってほしくないコマンド」を否定形で書いておくと、迷いがさらに減ります。

Windows / WSL のときに気をつけること

同じ症状でも、Windows で WSL を併用していると原因の層がもう一段増えます。エディタ本体が Windows 側で動き、エージェントのシェルが WSL（Linux）側で立ち上がる構成だと、参照されるのは Windows の PATH ではなく WSL の ~/.profile や ~/.bashrc です。この場合、settings.json で補うべきは terminal.integrated.env.windows ではなく、WSL 側の初期化ファイルになります。さらに Windows の実行ファイル（node.exe など）を WSL から呼ぼうとして混線することもあるので、「どちら側の node を使うのか」を最初に決めておくと迷いません。Linux 側に統一するなら、WSL のシェルで nvm を入れ直し、~/.profile に読み込みを書くのが結局いちばん素直です。

直ったかどうかを確かめる

設定を変えたら、エージェントを一度再起動してから確認するのが大切です。古いシェルセッションが残っていると、せっかく直した ~/.zshenv が反映されず「まだ動かない」と勘違いしがちです。再起動後、エージェントに次を実行させてください。

which node && node -v
which python3 && python3 --version

両方ともパスとバージョンが返ってくれば成功です。もし which node は通るのに node -v でエラーになる場合は、nvm の default が未設定（解決策3）か、.nvmrc の指すバージョンが未インストールのどちらかなので、nvm install 22 を一度実行させて切り分けます。

再発を防ぐために

最後に、原因を一言で押さえておきましょう。**「対話シェルでしか読まれない場所に PATH 設定を書いている」**のが根本です。バージョン管理ツールの初期化は ~/.zshenv / ~/.profile に、対話的な見た目（プロンプトや補完、エイリアス）は ~/.zshrc に、と置き場所を役割で分けておくと、エージェントに限らず cron や CI でも同じトラブルを踏まなくなります。

個人開発で複数のリポジトリを並行して触っていると、私はこの「役割で置き場所を分ける」習慣に何度も助けられてきました。最初に一度だけ整えておけば、新しいマシンに移っても、新しいエージェントを足しても、同じ初期化がそのまま効いてくれます。

エージェントが落ちると、つい AI 側の不調を疑いたくなります。けれど多くの場合、足元の環境がエージェントに正しく見えていないだけです。まずは echo $PATH を一度実行させてみる——それがこの種の問題の最短経路だと考えています。