Orbit / Getting notified when an agent is stuck

Getting notified when Claude Code is waiting for you

An agent that is waiting for you and an agent that is working look identical from across the room. Here are the ways to close that gap, starting with the free ones that need no new software.

This is a real gap rather than a preference. Two open issues on the Claude Code repository ask for exactly this, #36885 and #13024, and both still rank on searches for it.

Option 1: a Notification hook

Claude Code fires a Notification hook event when it wants your attention, which includes waiting on a permission prompt. You attach a shell command to it in your settings file at ~/.claude/settings.json, or per project in .claude/settings.json.

macOS

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"needs your input\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

Linux

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'needs your input'" }
        ]
      }
    ]
  }
}

Windows (PowerShell)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \"[console]::beep(880,300)\""
          }
        ]
      }
    ]
  }
}

The hooks schema has changed more than once. If a config that looks right does nothing, check the current shape in the Claude Code hooks documentation before assuming your command is broken, and run claude --debug to see whether the hook fires at all.

The same mechanism works for completion. Attach a command to the Stop event and you get a ping when a run ends rather than when it blocks.

Option 2: the terminal already does this

iTerm2 can watch for silence and tell you when output stops. Open the session menu, turn on Notify on next mark or set an alert for inactivity. It costs nothing and needs no config file. tmux does something similar with monitor-silence:

# ping me when this pane has been quiet for 15 seconds
tmux set-window-option monitor-silence 15
tmux set-option visual-silence on

Silence detection has an obvious flaw. An agent thinking hard about a large refactor is also silent, so you get pulled back for nothing. It works well enough for one agent and gets annoying fast with several.

Option 3: send it to your phone

Any of the hooks above can call a webhook instead of a local notifier, which puts the alert on your phone through ntfy, Pushover or a Slack incoming webhook:

curl -s -d "Claude Code needs input in $(basename "$PWD")" ntfy.sh/your-private-topic

Use a topic name nobody would guess, since ntfy topics are public by default.

Where all of this breaks

Every option above is a doorbell. It tells you somebody is at the door and nothing else. With one agent that is the whole problem solved. With six it is close to useless, for three reasons.

You do not know which agent rang. The notification names a hook, not a workspace. You go and check terminals until you find the one that stopped, which is the work you were trying to avoid.
You do not know what it asked. The question is on a screen somewhere. The notification does not carry it, so you cannot decide anything from the notification itself.
It is gone once you dismiss it. Notifications are events. Six of them arriving while you are in a meeting leaves you with no list at the end, just a feeling that something is waiting.

The underlying issue is that a notification is a nudge and what you actually need is a record. Something has to hold the state of every agent so you can look once and see the three that need you and the seven that do not.

What Orbit does instead

Orbit reads each agent's rendered terminal screen rather than parsing its stdout, because most CLIs draw prompts with cursor positioning and redraws that make a byte stream nearly unreadable. When the rendered screen matches a blocking prompt, that workspace flips to needs input and the question is attached to it. When the agent resumes, it flips back on its own.

Those states then rank into one queue. Blocked agents first, then work that passed your verify commands and is waiting for review, then errors, then agents that have stalled. You move with j and k, open with Enter, approve with A, merge with M. Nothing else asks for your attention, and nothing that needed it disappears because you were away.

It is not magic and it does get things wrong. Screen reading has false positives on agents that print prompt-shaped text without waiting, and a workspace can flip to needs-input for a second before flipping back. The tradeoff is deliberate: a false ping costs a glance, a missed block costs an hour of an agent sitting idle.

Push notifications to your phone are part of the paid tier, and they carry the question rather than just the alert, so you can answer from the couch and the agent picks up at your desk.

Which one should you use

If you are	Use
Running one agent at a time	A Notification hook. It is free, it takes two minutes, and nothing else is needed.
Running two or three, all in view	Hooks plus iTerm2 or tmux silence alerts.
Away from the desk a lot	A hook that posts to ntfy or Slack.
Running five or more at once	A doorbell stops scaling here. You need something holding state per agent, whether that is Orbit or something you build.

See the queue instead of the terminals

Free for individuals, no account. Point it at a repo and add a few tasks.

Download for Mac Download for Windows

Builds are unsigned; the install pages walk through the first launch on each platform.