Troubleshooting

The shell cannot find harness-cli#

This is usually a PATH problem. Test the bundled CLI directly to separate installation from daemon reachability:

/Applications/Harness.app/Contents/MacOS/harness-cli ping

When that works but harness-cli alone does not, reopen the shell after completing command-line setup, or follow the installation guide. Do not use zsh/bash export syntax in fish.

The CLI cannot reach the daemon#

Open Harness and try the checks below. Exit 4 indicates an unreachable daemon or failed remote tunnel, not a missing target.

harness-cli socket-path
harness-cli ping
harness-cli daemon-stats --json

Check whether HARNESS_SERVER points at a stale or unintended socket. For remote work, confirm plain SSH succeeds, then verify the remote binary path, daemon, and registered socket. Do not loosen socket permissions as a fix.

A target is missing or ambiguous#

harness-cli ls --json
harness-cli inspect

Exit 3 means Harness could not select a unique target. Use a full ID from the current daemon’s listing. Positions are contextual, labels may repeat, and a local ID does not identify a pane on a different host.

An agent is visible but not notifying#

Check macOS notification permission and Focus settings, then the event toggles in Settings → Notifications. Confirm the agent’s hook is installed on the machine and account where the agent runs.

For Hermes and OpenClaw, complete the documented manual step. Process detection alone is not equivalent to a tool emitting an explicit approval or completion event. Test the notification channel from a Harness pane:

harness-cli notify --surface "$HARNESS_SURFACE" --title "Harness test" --body "Notification check"

Sessions or history do not return#

Check Settings → Terminal → Experience and Keep sessions running. Plain mode defaults to ephemeral unpinned sessions. Check whether you explicitly closed the pane, restarted the daemon, or shut down the host.

For missing history, inspect history-limit and persist-scrollback, including pane-level overrides. Output produced while persistence was off is not recoverable from Harness’s saved log. A saved layout is not a checkpoint of running process memory.

Colors, shortcuts, or prompt navigation differ#

Use color-check and theme-preview to inspect rendering separately from application output. Check the effective keymap for overrides, and confirm shell integration is enabled when prompt navigation or command waiting is missing.

harness-cli color-check
harness-cli keymap --json
harness-cli config check

Change one setting at a time. Test shell-integration changes in a new shell rather than assuming an already-running shell was reinjected.

Create a useful issue#

• Record Harness version/build, macOS or Linux version, local versus remote context, and the experience mode.
• Describe the smallest reproducible sequence, expected behavior, and actual result.
• Include the relevant command, exit status, and a redacted diagnostic or capture.
• Remove tokens, private paths, hostnames, and sensitive terminal output before posting.

Use Issues in the public source repository. Do not attach a full terminal capture or configuration file without reviewing its contents.

Troubleshoot the new workspace tools#