Why a Claude Code background task can hang without anyone noticing, and the 2× rule, watchdog script and CLAUDE.md line that catch it.
Yesterday a Claude Code background task got stuck on a cloud box for two hours, and nobody noticed. The job was a dump step that normally finishes in about 20 minutes. It hung, wrote nothing, and my agent told me “still running” twice before I asked why something had been stuck for two hours without anyone checking.
Its answer was honest and useful: “The background waiter only fired when the job finished, so it had no way to notice a hang.” That’s the whole bug. Notify-on-exit is a great way to wait for a job that ends. A hung job never ends.
Claude Code’s agent list in the middle of the night: one subagent “Checking q5_dumpbuild.log progress” for 3h 4m, another waiting on a compile log for almost 2 hours.
This post covers why it happens, the one rule that fixes it, and a small script you can copy.
Why a background task can hang silently
When Claude Code starts a long command in the background (the Bash tool with run_in_background, or a background subagent), the agent goes off and does other work. It hears about the job again in one of two ways:
- The job exits, and Claude Code tells the agent it finished.
-
The agent decides to look: it reads the output file, runs
ps, or checks a timer it set.
Most setups rely only on the first. Even when the agent does set a timer, the interval is often arbitrary. In the same session I noticed every progress check it set was 40 minutes. When I asked why, it said: “40 minutes was a default I kept reusing, not a number based on anything.”
So you get three failure modes:
- Hung, not dead. The process is alive, using no CPU or spinning on a lock, and writing nothing. No exit, no notification.
- Passing on a sub-agent’s status. A subagent says “still running” and the main agent relays it without checking whether anything moved.
- Timer unrelated to the job. A 40-minute check on a 7-minute build means you lose 33 minutes every time it hangs.
People report the same thing on Claude Code’s issue tracker: background agents that sit in “running” with no progress indicator and no built-in timeout. So don’t wait for a fix upstream. Add the check yourself.
The fix: check at twice the usual time
The rule my agent now follows for every long job:
- Write down how long the job usually takes. The log usually already says so. The dump had finished in about 20 minutes every previous time.
- Check progress at 2× that. Not “is it alive”, but “did its output grow since the last check”.
- If nothing moved, step in: kill it, look at why, and restart or work with partial results.
With that rule, the 20-minute job would have been caught at 40 minutes instead of 120. When the agent reset its timers to match real durations, they came out as about 25 minutes for analysis runs that took 5 to 26 minutes and about 15 minutes for a 7-minute compile.
Why 2× and not 1.1×? Run times vary. Remote machines get slower hosts and builds hit cold caches, so a tight check fires on healthy jobs and the agent learns to ignore it. Twice the typical time is loose enough to stay quiet on a slow run and tight enough to catch a real hang the same hour.
A watchdog script you can copy
Here’s a small bash wrapper. It runs any command, and if the command’s log hasn’t grown for a set number of seconds, it kills the job and exits with a clear code. The agent hears about it through the normal notify-on-exit path, so a hang turns into an exit.
#!/usr/bin/env bash
# watchdog.sh: run a command, kill it if its log stops growing.
# usage: ./watchdog.sh <stall_seconds> <logfile> -- <command...>
set -u
STALL=$1; LOG=$2; shift 3
"$@" >"$LOG" 2>&1 &
PID=$!
last_size=-1; last_change=$(date +%s)
while kill -0 "$PID" 2>/dev/null; do
sleep 30
size=$(wc -c <"$LOG" 2>/dev/null || echo 0)
now=$(date +%s)
if [ "$size" != "$last_size" ]; then
last_size=$size; last_change=$now
elif [ $((now - last_change)) -ge "$STALL" ]; then
echo "WATCHDOG: no output for ${STALL}s, killing $PID" | tee -a "$LOG"
kill "$PID"; sleep 5; kill -9 "$PID" 2>/dev/null
exit 124
fi
done
wait "$PID"
Use it like this for a job that usually takes 20 minutes (1200 seconds). It kills the job after 40 minutes with no new output:
./watchdog.sh 2400 dump.log -- python make_dump.py --circuit big
Two notes:
-
Watch output growth, not wall time. A plain
timeout 2400also works when you know the total time, but it kills slow-but-healthy jobs too. Output growth tells you whether the job is doing anything. -
Some jobs are quiet by design. If a step legitimately prints nothing for 30 minutes, have it
toucha heartbeat file every few minutes and watch that file instead of the log.
On a remote box, do the same thing over SSH. And for the cloud bill, add sudo shutdown -h +240 when you start the box, so an idle machine turns itself off even if your login expires before the agent can stop it.
Tell the agent the rule once
The script only helps if the agent uses it. Put the rule in your CLAUDE.md (or the project's memory) so every session and subagent sees it:
## Long-running jobs
- Before starting any job expected to take >5 min, note its typical
duration (from logs or past runs) in your message.
- Run it through ./watchdog.sh with stall = 2× typical duration.
- Set your own progress check at 2× typical duration. Never reuse a
fixed default interval.
- When a subagent says "still running", check its output yourself
before passing that on.
The last line matters more than it looks. Twice in those two hours, the main agent relayed “still running” from a subagent without looking at the output itself.
What changed after
After the rule went in, the agent’s next long jobs got checks matched to their real durations: 25 minutes for an analysis run, 15 for a 7-minute build, instead of 40 for everything. The point is to hear about a hang from a check, not from my own “update?” two hours later.
None of this is specific to Claude Code. Any agent that waits on background work (an n8n workflow calling a slow API, a cron job on a VPS, a Codex run) has the same blind spot: an exit notification can’t report something that never exits. The fix is also the same: know the usual time, check at twice that, and treat “no new output” as a failure.
If you run agents or automations overnight and want a second pair of eyes on the longest job, send it to me on X (@priyanshudotsol). I’ll add a hang check to it for free.

Top comments (1)
We've experienced similar situations while building our platform. AI agents can save a lot of development time, but when they get stuck, debugging and waiting can sometimes take longer than doing the task manually. Monitoring and setting clear limits are just as important as automation. Great insight!