I run background workers with claude --bg and one main session that manages them. One night a worker asked for permission approval and just got ignored.. CC had it: the job file said blocked and approve Entering worktree. But my main session didn't know at all and in the agent list it's shown as idle.
So I added it to my small tool, agent-postmortem, that reads the files Claude Code already keeps. The session reads one line on its next tool call/prompt and if it has gone idle the line wakes it:
WORKER night-run (a1b2c3d4) blocked 15m: waiting for a permission approval (approve Entering worktree). A person must approve it: claude attach a1b2c3d4
Nothing needs to be setup. The plugin reads the claude --bg in the session's own Bash call and follows that worker, including questions, API errors and failures. A wake costs a turn, so it wakes a session at most once every 5 minutes, and it needs Claude Code 2.1.314 or later.
/plugin marketplace add zeyusuntt/agent-postmortem
/plugin install agent-postmortem@agent-postmortem
I developed it for my personal use and I found it's really useful. the first day it sent 12 lines, mostly "finished", and one was wrong: it called a healthy worker stalled. I changed that line the same day. this week it already caught 2 real workers stuck on permission, one of them on the same Entering worktree prompt..
also, last week I found 5 of my code review agents come back saying "completed" but actually the codex review they were supposed to run never started. nothing in the workflow output said it. it just failed silently and I only saw it by reading the transcripts. uvx agent-postmortem scan flags this kind of thing.
If you run claude --bg workers, try it and tell me where it's wrong. The one I most want to hear about is a worker that got stuck and it said nothing.
Top comments (5)
Does it also catch a worker that is blocked on something outside Claude Code, like a macOS permission dialog or a sudo prompt a tool spawned? Those look the same from the agent list: idle, no error.
We hit that a lot running computer-use agents (I'm on the Auten team), and the only signal was the last tool call never returning. A "no tool result for N minutes" line next to your permission check might cover that case.
Not yet. It only sees what Claude Code records, so a tool call that never returns reads as working. A stuck Bash call gets moved to the background at its timeout, and then the manager hears "finished". An MCP call can sit for hours with no line at all. A no-result timer looks right for that, and the hard part is not flagging slow builds. I'm trying it now. Thanks for the report.
One way to keep slow builds out: a long compile keeps burning CPU or printing output, while a process stuck on a prompt sits idle waiting for input. So "no tool result for N minutes AND the tool's process tree has been idle for that long" should catch the stuck ones without flagging the slow ones. Curious what threshold you land on.
Good idea, thanks, I'll try the process-tree check. No threshold yet: it didn't make this release, and I want to run it on real sessions before picking a number.
Update: 0.5.3 flags a background worker with no result from one tool call: at 10 minutes for an MCP call Claude Code moved to the background, at 30 for a call still open. Bash calls inside their timeout aren't flagged, so slow builds stay quiet. I looked at your process-tree check and left it out: a dialog and a slow remote service both look idle, and an MCP server is shared, so no process belongs to one call. Thanks for the report.