Six Old Processes Led Me to Build AgentDust

When my Mac started running hot, I looked at processes left around my AI coding sessions. I found six processes, each 7 to 9 days old: two development servers, a mock server, a browser driver, its MCP server, and a stale Node script. Three held ports. All six showed 0% CPU when I checked, so they were not the cause of the heat.

I had found them by checking the process list and launchctl by hand. I still had no safe rule for deciding what to stop.

There are related process leak reports for Claude Code and Codex. They describe the same class of lifecycle problem. They do not show that my six processes were all caused by those bugs.

A parent PID does not show whether work is abandoned

Killing every process whose parent PID is 1 sounds like a shortcut. In one test, a background Node job had parent PID 1 after 0.3 seconds even though the agent that launched it was still running. Parent PID describes a process relationship at that moment. It does not tell me whether the work is still needed.

Names and ports leave the same question unanswered. A process named node could be a test server, a mock, or part of an application I am using. A process holding a port is not necessarily active, abandoned, or safe to stop.

Track ownership while the session runs

I built AgentDust to associate a process with the Claude Code session whose marker it inherited. Hooks record session and shell events. At session start, a hook writes a random marker to Claude Code's environment file so child processes inherit it, and stores a keyed form in the local journal. During a survey, AgentDust hashes an inherited marker and compares it with the recorded key.

AgentDust records the agent identity so it can check whether the session's agent is still alive. Processes can be owned by a live session, owned by an ended session, suspect, managed, or unknown. Only processes owned by ended sessions and suspects can enter a cleanup plan. The doctor command only reads and reports.

Approval and revalidation

I approve a cleanup by typing a generated four-character code. The approval form does not accept a code supplied through the model's tool call. Before signaling, AgentDust takes a fresh process inventory, classifies each process again, and compares its boot session, PID, start time, user, and executable path with the identity in the plan. If a process no longer qualifies or its identity changed, AgentDust refuses to signal it. Otherwise it sends one SIGTERM to that PID.

A narrow PID reuse window remains between the last identity check and the signal call, because the operating system signal call takes a numeric PID. Revalidation reduces that risk but cannot remove it.

What I measured

The hook's measured median latency is 2.5 ms per event on a macos-15 runner. One KERN_PROCARGS2 fuzz run processed 27,196,230 inputs in 61 seconds without a crash. Two clean builds produced byte-identical binaries. The M0 report records these results.

AgentDust 0.1.0 supports Claude Code on macOS with Apple silicon. Install it with Homebrew, then connect it to Claude Code:

brew install hamzahamidi/agentdust/agentdust
agentdust setup

The cleanup skill is optional. To add it, run:

claude plugin marketplace add hamzahamidi/agentdust
claude plugin install agentdust@agentdust --scope user

Start a new Claude Code session and run /agentdust:cleanup. The repository has the implementation and setup details. The 0.1.0 release has the release artifacts.