Agents & notifications
See what is running, add explicit hooks, and jump to the work that needs you.
On this page
Start with automatic detection
Harness recognizes 23 coding CLI identities from the process tree: Claude Code, Codex, Cursor, OpenCode, OpenClaw, Gemini, Goose, Grok, Hermes, Kiro, OpenHands, Kimi, Aider, Cline, Kilo, Qwen, Vibe, Crush, Copilot, Amp, Droid, Auggie, and Pi. Identification does not require a hook. Compact brand badges use fixed identities rather than configurable agent colors.
Process/activity detection and explicit events are different signals. Install supported hooks for more precise notifications rather than assuming an idle process always means an approval request.
harness-cli list-agents
harness-cli list-agents --waitingInstall the supported hooks
Run the matching command on the machine where the agent stores its configuration. The installer backs up existing files and is idempotent. It uses the agent’s actual configuration format and adds Harness’s bin directory to hook command PATH values.
| Agent | Install command |
|---|---|
| Claude Code | harness-cli install-hooks claude-code |
| Codex | harness-cli install-hooks codex |
| Cursor Agent | harness-cli install-hooks cursor |
| Grok Build | harness-cli install-hooks grok |
| OpenCode | harness-cli install-hooks opencode |
| Pi | harness-cli install-hooks pi |
| Hermes | harness-cli install-hooks hermes |
| OpenClaw | harness-cli install-hooks openclaw |
Aider, Gemini, and Goose are detected, but the bundled installer does not provide hooks for them. Use built-in detection or an explicit notify command from your own tooling.
Enable the signals you need
Allow Harness notifications in macOS, then choose event types in Settings → Notifications: needs you, finished, failed, terminal bell, and long command finished. Check Focus settings when desktop notifications do not appear.
The first-run tour can install detected-agent hooks. Settings → Agents also provides a Copy Prompt setup path for an agent or IDE that can configure its own integration.
Go directly to waiting work
Press ⌘⇧U to jump to a waiting agent. The Workspace Overview (⌘⇧O) puts waiting tabs first and supports filtering by typing. Status appears across the tab, session row, and notifications so it remains connected to its source.
Agent Workspace foregrounds these controls, but detection remains available in the other experience modes.
Send a notification from your own tool
Inside a Harness pane, HARNESS_SURFACE identifies that pane. Use it to direct a notification to the right place:
harness-cli notify --surface "$HARNESS_SURFACE" --title "Build" --body "Ready for review"Installed hooks also emit OSC 7501 program-status reports. Use the dedicated program-status guide when your tool needs structured working, blocked, done, or error state rather than only a message.
Activity across hosts
Open Session → Activity… or the sidebar Activity control. The notification bell opens the same view filtered to attention. Each row identifies its host, session, tab, and source pane; linked views of one surface are deduplicated.
Choose a row or a system notification to open its exact pane. A closed pane or disconnected host is reported rather than silently targeting another pane. Program-status and hook reports are explicit; process/activity detection is labeled as inferred.
| Action | What changes |
|---|---|
| Mark read | Acknowledges the event, not the program’s blocked state or timestamp. |
| Snooze | Mutes reminders for 15 minutes or 1 hour. Resume to stop snoozing. |
| Duplicate alerts | Same-kind alerts are suppressed for 15 seconds; a different kind may still notify. |
Source references Harness 2.0.1
Checked against the immutable shipping commit for Harness 2.0.1. For other versions, consult the installed CLI’s help and schemas.