Six Old Processes Led Me to Build AgentDust

Description and use

AgentDust tracks processes linked to Claude Code sessions and safely cleans up stale ones, reducing heat and resource usage.

Problem

Uncontrolled background processes from AI coding sessions accumulate, causing system heat and resource waste.

Outcome

AgentDust reduces lingering processes, lowers CPU heat, and provides a safe cleanup workflow for AI coding sessions.

Workflow

• 1. Install AgentDust via Homebrew and set it up.
• 2. Hook writes a random marker to Claude Code’s environment file at session start.
• 3. AgentDust records the marker and session identity in a local journal.
• 4. During cleanup, AgentDust hashes inherited markers and compares with recorded keys.
• 5. Classify processes as live, ended, suspect, or unknown.
• 6. Generate a four‑character approval code and re‑validate process identity before sending SIGTERM.
• 7. Execute cleanup via /agentdust:cleanup in Claude Code.

Evidence

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.

Source

I built AgentDust to associate a process with the Claude Code session whose marker it inherited.

Source

Only processes owned by ended sessions and suspects can enter a cleanup plan. The doctor command only reads and reports.

Source

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.

Source

The hook's measured median latency is 2.5 ms per event on a macos-15 runner.

Source