fix: ensure codegraph is in PATH via ~/.pilot/bin symlink

Two-part fix for 'codegraph: not found' in hooks:

1. Installer: after npm install, symlink codegraph (and probe) into
   ~/.pilot/bin/ which is already in PATH via shell integration.
   This ensures the binary is findable regardless of nvm version
   or npm global bin PATH configuration.

2. Hooks: add 'command -v' guard so hooks silently skip if codegraph
   isn't installed yet (graceful degradation for fresh installs
   before the installer runs).

Author: maxritter

installer/steps/dependencies.py

@@ -4,6 +4,7 @@
 
 import json
 import os
+import shutil
 import subprocess
 import time
 from pathlib import Path
@@ -132,9 +133,12 @@ def _is_probe_installed() -> bool:
 
 def install_probe() -> bool:
     """Install Probe code search tool globally via npm."""
-    if _is_probe_installed():
-        return True
-    return _run_bash_with_retry(npm_global_cmd("npm install -g @probelabs/probe"))
+    if not _is_probe_installed():
+        if not _run_bash_with_retry(npm_global_cmd("npm install -g @probelabs/probe")):
+            return False
+
+    _symlink_to_pilot_bin("probe")
+    return True
 
 
 
@@ -182,15 +186,41 @@ def _is_codegraph_installed() -> bool:
         return False
 
 
+def _symlink_to_pilot_bin(binary_name: str) -> None:
+    """Create a symlink in ~/.pilot/bin/ pointing to the npm global binary.
+
+    This ensures the binary is in PATH even when the npm global bin directory
+    (e.g. ~/.nvm/versions/node/vXX/bin/) is not in PATH during hook execution.
+    ~/.pilot/bin/ is added to PATH by the shell integration step.
+    """
+    pilot_bin = Path.home() / ".pilot" / "bin"
+    pilot_bin.mkdir(parents=True, exist_ok=True)
+    link_path = pilot_bin / binary_name
+
+    source = shutil.which(binary_name)
+    if not source:
+        return
+
+    source_path = Path(source).resolve()
+    try:
+        if link_path.is_symlink() or link_path.exists():
+            link_path.unlink()
+        link_path.symlink_to(source_path)
+    except OSError:
+        pass
+
+
 def install_codegraph() -> bool:
     """Install CodeGraph for code knowledge graph and structural analysis."""
-    if _is_codegraph_installed():
-        return True
+    if not _is_codegraph_installed():
+        if not _run_bash_with_retry(
+            npm_global_cmd("npm install -g @colbymchenry/codegraph --force"),
+            timeout=120,
+        ):
+            return False
 
-    return _run_bash_with_retry(
-        npm_global_cmd("npm install -g @colbymchenry/codegraph --force"),
-        timeout=120,
-    )
+    _symlink_to_pilot_bin("codegraph")
+    return True
 
 
 def _is_vtsls_installed() -> bool:

installer/tests/unit/steps/test_dependencies.py

@@ -283,20 +283,23 @@ def test_install_codegraph_exists(self):
 
         assert callable(install_codegraph)
 
+    @patch("installer.steps.dependencies._symlink_to_pilot_bin")
     @patch("installer.steps.dependencies._is_codegraph_installed", return_value=True)
-    def test_install_codegraph_skips_if_already_installed(self, _mock_check):
-        """install_codegraph skips installation when already installed."""
+    def test_install_codegraph_skips_npm_if_already_installed(self, _mock_check, mock_symlink):
+        """install_codegraph skips npm but still creates symlink."""
         from installer.steps.dependencies import install_codegraph
 
         with patch("installer.steps.dependencies._run_bash_with_retry") as mock_bash:
             result = install_codegraph()
 
         assert result is True
         mock_bash.assert_not_called()
+        mock_symlink.assert_called_once_with("codegraph")
 
+    @patch("installer.steps.dependencies._symlink_to_pilot_bin")
     @patch("installer.steps.dependencies._is_codegraph_installed", return_value=False)
-    def test_install_codegraph_runs_npm_when_not_installed(self, _mock_check):
-        """install_codegraph runs npm install when not installed."""
+    def test_install_codegraph_runs_npm_when_not_installed(self, _mock_check, mock_symlink):
+        """install_codegraph runs npm install and creates symlink."""
         from installer.steps.dependencies import install_codegraph
 
         with patch("installer.steps.dependencies._run_bash_with_retry", return_value=True) as mock_bash:
@@ -307,9 +310,11 @@ def test_install_codegraph_runs_npm_when_not_installed(self, _mock_check):
         call_args = str(mock_bash.call_args)
         assert "@colbymchenry/codegraph" in call_args
         assert "--force" in call_args
+        mock_symlink.assert_called_once_with("codegraph")
 
+    @patch("installer.steps.dependencies._symlink_to_pilot_bin")
     @patch("installer.steps.dependencies._is_codegraph_installed", return_value=False)
-    def test_install_codegraph_returns_false_when_npm_fails(self, _mock_check):
+    def test_install_codegraph_returns_false_when_npm_fails(self, _mock_check, _mock_symlink):
         """install_codegraph returns False when npm install fails."""
         from installer.steps.dependencies import install_codegraph
 
@@ -319,6 +324,68 @@ def test_install_codegraph_returns_false_when_npm_fails(self, _mock_check):
         assert result is False
 
 
+class TestSymlinkToPilotBin:
+    """Tests for _symlink_to_pilot_bin() — creates symlinks in ~/.pilot/bin/."""
+
+    def test_creates_symlink_when_binary_exists(self, tmp_path: Path):
+        """Creates a symlink in pilot bin dir pointing to the real binary."""
+        from installer.steps.dependencies import _symlink_to_pilot_bin
+
+        fake_bin = tmp_path / "src" / "codegraph"
+        fake_bin.parent.mkdir(parents=True)
+        fake_bin.write_text("#!/bin/sh\n")
+        fake_bin.chmod(0o755)
+
+        pilot_bin = tmp_path / "pilot_bin"
+
+        with (
+            patch("installer.steps.dependencies.shutil.which", return_value=str(fake_bin)),
+            patch("installer.steps.dependencies.Path.home", return_value=tmp_path),
+        ):
+            pilot_bin_dir = tmp_path / ".pilot" / "bin"
+            pilot_bin_dir.mkdir(parents=True, exist_ok=True)
+            _symlink_to_pilot_bin("codegraph")
+
+        link = tmp_path / ".pilot" / "bin" / "codegraph"
+        assert link.is_symlink()
+        assert link.resolve() == fake_bin.resolve()
+
+    def test_skips_when_binary_not_found(self, tmp_path: Path):
+        """Does nothing when the binary is not in PATH."""
+        from installer.steps.dependencies import _symlink_to_pilot_bin
+
+        with (
+            patch("installer.steps.dependencies.shutil.which", return_value=None),
+            patch("installer.steps.dependencies.Path.home", return_value=tmp_path),
+        ):
+            _symlink_to_pilot_bin("codegraph")
+
+        link = tmp_path / ".pilot" / "bin" / "codegraph"
+        assert not link.exists()
+
+    def test_replaces_existing_symlink(self, tmp_path: Path):
+        """Replaces an existing symlink with the new target."""
+        from installer.steps.dependencies import _symlink_to_pilot_bin
+
+        fake_bin = tmp_path / "new_codegraph"
+        fake_bin.write_text("#!/bin/sh\n")
+        fake_bin.chmod(0o755)
+
+        pilot_bin_dir = tmp_path / ".pilot" / "bin"
+        pilot_bin_dir.mkdir(parents=True)
+        old_link = pilot_bin_dir / "codegraph"
+        old_link.symlink_to("/nonexistent/old/path")
+
+        with (
+            patch("installer.steps.dependencies.shutil.which", return_value=str(fake_bin)),
+            patch("installer.steps.dependencies.Path.home", return_value=tmp_path),
+        ):
+            _symlink_to_pilot_bin("codegraph")
+
+        assert old_link.is_symlink()
+        assert old_link.resolve() == fake_bin.resolve()
+
+
 class TestInstallPluginDependencies:
     """Test plugin dependencies installation via bun/npm install."""
 

pilot/hooks/hooks.json

@@ -23,7 +23,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "codegraph init -i && codegraph sync",
+            "command": "command -v codegraph >/dev/null 2>&1 && codegraph init -i && codegraph sync || true",
             "async": true,
             "timeout": 120
           }
@@ -96,8 +96,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "codegraph mark-dirty",
-            "async": true
+            "command": "command -v codegraph >/dev/null 2>&1 && codegraph mark-dirty || true",
+            "async": true,
+            "timeout": 10
           }
         ]
       },
@@ -146,7 +147,9 @@
           },
           {
             "type": "command",
-            "command": "codegraph sync-if-dirty"
+            "command": "command -v codegraph >/dev/null 2>&1 && codegraph sync-if-dirty || true",
+            "async": true,
+            "timeout": 30
           }
         ]
       }