Why I built AgentDust
Published
My Mac was running hot, so I started looking at processes I could close. I found six leftover processes that were 7 to 9 days old: two dev servers, a mock server, a browser driver with its MCP server, and a stale Node script. Three held ports, and all six were idle at 0% CPU. They were not the cause of the heat. I still had to inspect them by hand, without a clear way to tell which ones were safe to stop. I recorded the counts and measurements in the README.
Users have reported similar orphaned helper processes in Claude Code and Codex.
A parent process is not proof
At first, looking for processes adopted by launchd seemed like a simple way to find leftovers. It was not. A background Node job from an agent that was still running had parent PID 1 after 0.3 seconds. macOS had already reparented the job to launchd. Its current parent did not say whether the agent still needed it.
Process names have the same problem. A node process could be a development server from an active session or something unrelated. Killing by name or parent alone can stop live work.
Record ownership before cleanup
After setup, AgentDust records Claude Code session and shell events in a local journal. agentdust doctor uses that journal to list processes and explain how they were classified. A plan narrows the list to processes that may be cleaned up.
I approve cleanup by typing the code AgentDust generates, either in Claude Code or in the terminal. AgentDust groups processes from ended sessions under a shared code and gives each suspect its own code (approval flow). Just before sending SIGTERM, AgentDust classifies the process again and checks its boot session, PID, start time, user and executable path. It then signals that process only. Approval comes from me, not a model tool call.
Where it is now
The 0.1.0 release supports Claude Code on macOS with Apple silicon. Codex and Cursor support are not in this release. I started with Claude Code on macOS.
The AgentDust repository has the source and design notes.