How to Get Notified When Claude Code Needs You on Your Server

TL;DR

Agent Monitor (Premium) reads status files written by a small hook you add to Claude Code, plus a process scan as a fallback. It shows running, waiting, done or error per agent, and can notify you when one starts waiting or errors. It works with Claude Code, and the hook must be installed on the server.

The problem

You start Claude Code on a server, give it a long task and go and do something else. It stops to ask a question or hits an error within minutes, and then sits idle for an hour because you didn’t know. Checking every few minutes defeats the point of leaving it alone. Terminal notifications don’t help when the session is on a remote machine and your laptop is closed.

How Agent Monitor works

It’s agentless in the sense that nothing runs permanently on the server. Two sources of information are read over SSH:

  1. Hook status files (reliable). Claude Code supports hooks. ServerPanel gives you a small zero-dependency shell script and a snippet for ~/.claude/settings.json. The hook records state to ~/.serverpanel/agents/: running when you submit a prompt, waiting when Claude Code sends a notification asking for you, done when it stops.
  2. A process scan (fallback). The app also looks at running processes. If a hook entry exists for the same agent, the hook wins.

States shown: running, waiting, done, error, sorted so the ones needing attention are first.

Set it up

  1. Open the server’s dashboard → ••• → Agent Monitor (Premium).
  2. Open the setup sheet and copy the script and settings snippet.
  3. Install the script on the server and add the hook entries to Claude Code’s settings. This is your server config, so the app gives you the text to copy rather than editing it.
  4. Start Claude Code and open Agent Monitor. The list refreshes about every 8 seconds while it’s on screen.

Push notifications

In Settings → Agents, turn on Agent Alerts. ServerPanel then checks your servers in the background and sends a local notification when an agent enters waiting or error. It doesn’t repeat while the agent stays in that state. Tapping the notification opens that server’s agent list.

What to expect

  • Delays. Background checks run on iOS’s schedule, not instantly. Don’t depend on it for time-critical decisions.
  • Hook required for good status. Without the hook you only get what the process scan can infer.
  • One server at a time on screen, but alerts cover all your servers.
  • Premium. The monitor and alerts are Premium features.

Handy together

Use the compose bar to answer the agent from your phone, and the tmux switcher to get back to its session.

FAQ

Does it support agents other than Claude Code? It is built around Claude Code. Other agents may appear from the process scan, but status through hooks is for Claude Code.

How does it know the agent is waiting? A small hook script, which you add to Claude Code’s settings, writes a status file when Claude Code starts working, asks for input or finishes. ServerPanel reads those files over SSH.

Will I get a notification when it’s done? Pushes are sent when an agent starts needing attention (waiting or error), once per change. Done is shown in the list.

Is it real time in the background? No. Background checks happen when iOS allows, so notifications can be delayed.

The app ServerPanel →