Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
203 lines (133 loc) · 3.34 KB

TROUBLESHOOTING.md

File metadata and controls

203 lines (133 loc) · 3.34 KB

Troubleshooting

If setup fails, run this first:

npm run doctor

This checks your local environment and prints pass/fail status without changing your system.

Install Fails with "gyp" or "make" Errors

Install Xcode Command Line Tools, then retry:

xcode-select --install
npm install

Install Fails with ModuleNotFoundError: No module named 'distutils'

Python 3.12+ removed distutils. Install setuptools:

python3 -m pip install --upgrade pip setuptools
npm install

If that still fails, install Python 3.11 and point npm to it:

brew install python@3.11
npm config set python $(brew --prefix python@3.11)/bin/python3.11
npm install

To undo that Python override later:

npm config delete python

Install Fails with fatal error: 'functional' file not found

C++ headers are missing/broken, usually due to Xcode CLT issues.

Check toolchain first:

xcode-select -p
xcrun --sdk macosx --show-sdk-path

If either command fails (or the error persists), reinstall CLT:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Then retry:

npm install

If CLT is installed but the error still appears on newer macOS versions, compile explicitly against the SDK include path:

SDK=$(xcrun --sdk macosx --show-sdk-path)
clang++ -std=c++17 -isysroot "$SDK" -I"$SDK/usr/include/c++/v1" -x c++ - -o /dev/null <<'EOF'
#include <functional>
int main() { return 0; }
EOF

Install Fails on node-pty

node-pty is native and requires macOS toolchains. Confirm:

  • macOS 13+
  • Xcode CLT installed
  • Python 3 with setuptools/distutils available

Then retry npm install.

App Launches but No Claude Response

Verify Claude CLI is installed and authenticated:

claude --version
claude

⌥ + Space Does Not Toggle

Grant Accessibility permissions:

  • System Settings -> Privacy & Security -> Accessibility

Fallback shortcut:

  • Cmd+Shift+K

Packaged App Won't Open (Security Warning)

The .app built by npm run dist is unsigned. macOS Gatekeeper blocks unsigned apps by default.

To allow it:

  1. Open System Settings → Privacy & Security
  2. Scroll to the security section
  3. Click Open Anyway next to the Clui CC message

You only need to do this once. This is a local build, not App Store distribution.

Install Fails at Whisper Step

The installer requires Whisper for voice input. If it fails:

  1. Make sure Homebrew is installed:
brew --version

If not, install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. Install Whisper manually:
brew install whisper-cli
  1. Rerun the installer:
./install-app.command

Install Fails at Build Step

Run the steps manually to see the detailed error:

./commands/setup.command
npm run dist

If npm run dist fails, try a clean reinstall:

rm -rf node_modules
npm install
npm run dist

Marketplace Shows "Failed to Load"

Expected when offline. Marketplace needs internet access; core app features continue to work.

Window Is Invisible / No UI

Try:

  • ⌥ + Space
  • Cmd+Shift+K
  • Confirm app is running from the menu bar tray