capture hooks cannot find CLI installed to ~/.local/bin

[dpearson2699]

Summary

The install guide installs/symlinks the iai-mcp CLI at ~/.local/bin/iai-mcp, but the installed Claude hook scripts do not include that path in their CLI discovery candidates. In a Claude hook runtime that does not inherit the user's interactive shell PATH, hooks can be reported as ACTIVE while still logging skipped: iai-mcp CLI not found and silently skipping recall/capture work.

Environment

• iai-mcp version: 0.4.2
• iai-mcp commit: 5df9101
• macOS version: macOS-26.4.1-arm64-arm-64bit
• Python version: 3.12.13
• Node version: v22.22.1
• MCP host: Claude Code
• Install path: local editable checkout with CLI symlinked at ~/.local/bin/iai-mcp

Steps to reproduce

1. Follow the README/install guide with bash scripts/install.sh.
2. Let the installer create the global CLI symlink at ~/.local/bin/iai-mcp.
3. Install hooks with iai-mcp capture-hooks install.
4. Run iai-mcp capture-hooks status.
5. Start/use Claude Code in an environment where hook scripts do not inherit an interactive shell PATH containing ~/.local/bin.
6. Check the iai-mcp hook logs under ~/.iai-mcp/logs/.

Expected behaviour

The installed hooks should find the CLI installed by the installer/README without requiring an additional manual cache file or shell PATH inheritance.

Actual behaviour

iai-mcp capture-hooks status reports the hooks are wired and active, but hook execution can log:

skipped: iai-mcp CLI not found

In this state, recall/capture hook work is skipped even though the install guide's CLI symlink exists.

Evidence

The installer creates the symlink:

~/.local/bin/iai-mcp -> <repo>/.venv/bin/iai-mcp

The installed hook scripts locate the CLI using:

1. IAI_MCP_SESSION_RECALL_CLI / IAI_MCP_SESSION_CAPTURE_CLI
2. ~/.iai-mcp/.cli-path
3. hard-coded candidates:
   • $HOME/IAI-MCP/.venv/bin/iai-mcp
   • /usr/local/bin/iai-mcp

They do not include:

$HOME/.local/bin/iai-mcp

The local workaround was to create:

~/.iai-mcp/.cli-path

with the absolute path:

/Users/dpearson/.local/bin/iai-mcp

After that, hook CLI discovery has a deterministic path independent of ambient shell PATH.

Suspected cause

The installer and the hook templates disagree about the canonical guide-installed CLI location. The installer uses ~/.local/bin, while the hooks only try /usr/local/bin and an uppercase $HOME/IAI-MCP checkout path unless the cache/env override is already populated.

Suggested fix

Any of these should make the guide install self-consistent:

1. Add $HOME/.local/bin/iai-mcp to the hook candidate list.
2. Have the installer write ~/.iai-mcp/.cli-path with the symlink target or ~/.local/bin/iai-mcp during install.
3. Export PATH="$HOME/.local/bin:$PATH" inside the installed hook scripts before attempting CLI lookup.

Option 1 or 2 seems preferable because hook success should not depend on the MCP host inheriting an interactive shell PATH.

[CodeAbra]

Working on it. Thanks!