This page covers what to do when Harpax won't download, won't launch, or launches but doesn't start monitoring your sessions. Work through the symptoms in order — most issues are caught by the Launch page's automatic health checks.

Start here: run the health checks

Every time you open Harpax, the Launch page runs a battery of automated checks. If any of them fail, that's almost always the right place to start:

  • Daemon binary is present and executable
  • Claude hooks are correctly configured in settings.json
  • The Harpax MCP server is registered with Claude
  • The sessions directory exists and is writable
  • Your config file is valid YAML
  • Ports 9850, 9851, and 9852 are available

Failed checks often display a Fix button that resolves them automatically. Try that first.

Symptom: the download failed or the installer won't run

Pre-installation issues depend on how you obtained Harpax (direct download, package manager, etc.). Once you have a binary in hand, jump to the next section.

  • Browser blocked the download. Some browsers flag newly published binaries until they reach a reputation threshold. Choose "Keep" or "Allow" in your browser's download manager.
  • Windows SmartScreen warning. Click More info → Run anyway. The warning appears for any binary that hasn't accumulated enough installations to be recognized.
  • macOS Gatekeeper warning. Right-click the app, choose Open, then confirm. Do not double-click on first run.
  • Antivirus quarantine. Add an exclusion for the Harpax binary and the ~/.harpax/ directory.

Symptom: Harpax launches but the daemon won't start

Open a terminal and run harpax serve directly — the output will point at the problem. The most common causes:

Port conflict

Harpax needs three loopback ports:

  • 9850 — WebSocket bridge (GUI ↔ daemon)
  • 9851 — IPC server (hook verdicts)
  • 9852 — MCP server (allowed-action re-injection)

If another process is holding any of these, the daemon will refuse to start. Find and stop the conflicting process, or change the ports in ~/.harpax/config.yaml under the shim block.

# Windows
netstat -ano | findstr "9850 9851 9852"

# macOS / Linux
lsof -i :9850 -i :9851 -i :9852

Sessions directory not writable

Harpax writes JSONL session files to ~/.harpax/sessions by default. If that path isn't writable (permissions issue, full disk, or a custom path that doesn't exist), the daemon fails on startup. Create the directory manually if needed, or override the path in config.yaml:

storage:
  path: /a/path/you/can/write/to

Symptom: Harpax is running but isn't seeing any session activity

The daemon is up, the GUI shows "Connected," but nothing appears in the live monitor when you use Claude Code. This is almost always a hook configuration problem.

Windows: settings.json paths must use forward slashes

Claude's hook runner cannot parse Windows backslash paths in settings.json. If you edited the file manually and used backslashes, the hooks will silently fail to spawn.

Re-run Harpax's startup auto-configuration (or click Fix on the Hooks health check), which writes the path with forward slashes via filepath.ToSlash().

Other hook issues to check

  • Hook client binary is missing. The hook entry in settings.json points to hook-client.exe (or its Unix equivalent). Make sure the file exists at that exact path.
  • Claude Code isn't reading the right settings file. Claude looks at user-level settings first, then project-level. Confirm which file Harpax wrote to via the Setup page in the GUI.
  • Hooks are configured for the wrong events. Harpax needs PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, and SessionEnd. If only some are registered, only some events will arrive.
  • Hook timeout too low. The default performance.hook_timeout_ms is 2000. On slow disks or constrained machines, hooks can time out before the daemon responds — raise the limit if you see warn_on_slow_hook messages in the logs.

Symptom: blocks aren't enforced

Events appear in the live monitor and detections fire, but dangerous tool calls still execute. The most likely cause:

  • You're in passive mode. Passive mode logs everything but never blocks. Switch protection.mode to active in your config (or use the Shim Mode toggle on the Settings page).
  • The detection fired at a non-critical level. By default, only critical severity blocks; high warns. Adjust protection.severity_actions if you want a stricter posture.
  • The pattern is in your allowlist. Check ~/.harpax/allowlist.yaml or the Allowlist section in Settings.

Where to look for logs

  • ~/.harpax/logs/daemon.log — daemon output, including hook IPC events and detection decisions
  • ~/.harpax/sessions/<session-id>.jsonl — raw event stream for a specific session
  • The browser dev tools console inside the GUI for frontend errors

Still stuck?

If you've worked through the checks above and Harpax still isn't behaving, open a support ticket. Include:

  • Operating system and version
  • Harpax version (run harpax version)
  • The output of harpax serve from a terminal
  • The contents of settings.json (with any secrets redacted)
  • A recent session JSONL file if the issue is detection-related

See How do I connect with the Cambric team? for the support channels.