AgentDust

AgentDust is a local companion for AI coding agents. It helps Claude Code and Codex diagnose and clean up leftover processes, recover busy TCP ports, and report cleanup outcomes. Claude Code disk usage is available on macOS. Manual cleanup requires your typed approval. Automatic cleanup is opt-in and limited to processes proven to belong exclusively to ended sessions in directories you enable. Homebrew provides macOS arm64 binaries. npm and release archives support macOS arm64 and Linux x86_64 on Ubuntu 24.04, including Ubuntu 24.04 x86_64 under WSL2.

AgentDust 1.8.1 supports Claude Code and Codex process tracking and cleanup on macOS arm64 and Linux x86_64 on Ubuntu 24.04, including Ubuntu 24.04 x86_64 under WSL2, with local outcome metrics and worker version status. Linux and WSL2 require a writable ext4 data directory. In WSL2, the agent and AgentDust must run in the same distribution. The exact 1.7.1 Linux archive and npm package passed WSL2 acceptance in release run 38104539057; each release repeats acceptance on its exact artifacts. Linux automatic cleanup uses systemd user services. Codex desktop cleanup waits until every recorded host process exits. Agent Teams remain outside the support claim. Claude Code disk usage remains macOS only. Claude Code fixture coverage includes the documented concurrent session, subagent and lifecycle scenarios through 2.1.292, including abrupt exit (M6 fixture matrix). Historical acceptance evidence: the installed 1.0.0 Homebrew binary passed controlled human decline and typed approval checks on the maintainer's Mac (release evidence). See install and connect. To try the non-destructive approval flow, run the development probe.

Agents start dev servers, MCP servers and helpers. When a session ends or crashes, some of them keep running under launchd or systemd, holding memory, ports and sometimes CPU. The upstream reports are open: anthropics/claude-code#1935 and openai/codex#21008.

Security and privacy: SECURITY.md, the threat model and the section below.

Status

AgentDust 1.8.1 provides process analysis, opt-in automatic cleanup, approved manual cleanup, local cleanup outcome metrics and automatic worker version status for Claude Code and Codex on macOS arm64 and Linux x86_64, including Ubuntu 24.04 x86_64 under WSL2, plus a read-only Claude Code disk report on macOS. Automatic cleanup results include the time they were recorded. Status identifies whether the running worker build matches the CLI build. If the versions differ after an upgrade, run agentdust auto resume from the installed binary. Codex support retains the exact host-exit requirement; it does not stop helpers immediately when a desktop chat ends. Cursor remains deferred. The milestones are in ROADMAP.md.

Releases follow Semantic Versioning: compatible fixes increment the patch version, compatible features increment the minor version, and incompatible public API changes increment the major version.

| Part | State | | --- | --- | | TCP port diagnosis and recovery | agentdust port PORT [--resolve] [--json] and agentdust_port. Recovery uses the existing automatic policy (scope and limits) | | Local cleanup outcome metrics | agentdust metrics [--json] and agentdust_metrics; private local history with size based retention (limits) | | Opt-in automatic cleanup | Available since 1.1.0. Directory policy, owner-exit worker and read-only agent results with per-result record times (commands and limits) | | Process identity, named session markers read from another process, KERN_PROCARGS2 parser (fuzzed) | Built | | Claude Code and Codex hooks that record session and shell events in a local journal | Built | | agentdust setup codex | Six user hooks, native MCP registration, diff, consent, check and removal (Codex support and limits) | | Journal rotation and retention | Runs in the automatic worker when due; hooks, doctor, status and plan requests do not run maintenance | | MCP approval probe: a typed-code form that changes nothing | Built | | Reproducible release pipeline | The GitHub Actions dry run built two identical binaries, packaged a deterministic tarball, and verified the binary, tarball and SBOM attestations (M0 report, 0.1.0 run) | | Homebrew distribution | Available from the AgentDust tap for macOS on Apple silicon | | Linux support | Ubuntu 24.04 x86_64 with Claude Code and Codex; writable ext4 data directory | | npm distribution | macOS arm64 and Linux x86_64; npm selects the matching native binary | | Release workflow: tag gate, audit, two builds, tarball, SBOM, attestation, draft release, formula | Built (release process) | | agentdust setup for Claude Code (hooks in settings.json, the MCP server through the claude CLI, a diff and consent, --check, --remove) and agentdust status | Built (setup) | | agentdust doctor, the MCP doctor and plan tools, and cleanup through the MCP form or terminal approval | Built for release 0.1.0 (apply design and limits) | | Read-only Claude Code disk report and skill | agentdust disk [--json], agentdust_disk and /agentdust:disk (scope and limits) | | Optional Claude Code skills | Available as the agentdust plugin marketplace below |

Resolve a busy TCP port

Ask Claude or Codex: “Check what holds port 3000 and clean up a proven leftover.” With the AgentDust cleanup skill available, when a server start it initiated fails with EADDRINUSE, the agent can diagnose the port, attempt automatic cleanup for proven leftovers under your existing enabled-project policy, and retry that same start once after a fresh scan shows no visible listener. The agentdust_port tool diagnoses listeners by default. With resolve: true, it attempts cleanup under your existing enabled-project policy, then checks listeners again. Uncertain actionable processes require typed approval through the existing plan/apply flow.

agentdust port 3000
agentdust port 3000 --resolve --json

A port number does not grant permission to stop its listener. Live, kept, unknown and managed processes remain protected. Results cover current-user-visible IPv4/IPv6 TCP listeners. A process may be omitted when its identity or socket descriptors cannot be read. no_visible_listener is an observation, not a guarantee that a bind will succeed. See port conflict recovery.

Connect Codex

agentdust setup codex --yes
agentdust setup codex --check

After setup, review and trust the six AgentDust hooks in Codex /hooks, then start a new chat. Codex requires this trust review before user hooks execute. An AI agent can perform setup after you authorize it; setup does not bypass Codex hook trust.

The same directory policy covers Claude Code and Codex. Dedicated Codex runtimes qualify for automatic cleanup after they exit. A desktop chat can share a live server with other chats, so its helpers stay protected until every recorded host has exited. Uncertain cases still require approval. See Codex support and limits.

Inspect Claude Code disk usage

agentdust disk
agentdust disk --json

In Claude Code, ask “Use AgentDust to show where Claude Code uses disk space”, or use /agentdust:disk from the optional plugin. The agentdust_disk tool reads metadata under the Claude configuration root and the current project's .claude/worktrees. It reports logical and allocated bytes by purpose, marks partial scans and deletes nothing. Allocated bytes are not reclaimable space. See scope, categories and limits.

How cleanup works

1. agentdust doctor lists processes that look left behind and says why, with a class for each, such as owned by an ended session, suspect or unknown.
2. A plan keeps only processes owned by an ended session and suspects, at most 10 per call. You approve by typing a 4-character code that AgentDust generates: one code for the whole batch of owned processes, and one code per suspect with its evidence. The form is in your agent, or in the terminal with agentdust apply.
3. Before signalling each process, AgentDust classifies it again and compares boot session, PID, start time, user and executable path. It sends SIGTERM to that one PID and nothing else.

Cleanup metrics

agentdust metrics
agentdust metrics --json

AgentDust 1.6.0 records manual and automatic executor outcomes, plus automatic policy skips, in a private local JSONL file. The JSON summary includes totals by result and cleanup mode, classifier counts, and daily buckets for charts. The read-only agentdust_metrics MCP tool returns the same summary to agents. Calls rejected before an item reaches the executor are not included. Counts are outcomes, not unique processes; repeated attempts may add more rows. Records contain only the time, mode, class and result. They do not contain PIDs, process names, paths, commands, session IDs or project names. AgentDust does not upload metrics. An MCP host may include the returned summary in requests to its model service, and timestamps and counts can reveal activity patterns. The log keeps its current 5 MiB file and one rotated file. Retention is based on file size, with no age-based expiration or guaranteed history window. Metrics history starts with the first cleanup result recorded by a build that supports this feature. If a metrics write fails, AgentDust prints a sanitized warning to stderr and continues the cleanup result.

terminated means the selected process disappeared during AgentDust's exit check. It does not estimate time, CPU or memory saved. See metrics data and limits.

The design is in docs/superpowers/specs.

Why I built AgentDust

My Mac was running hot, so I looked for leftovers from my AI coding sessions. Six leftover processes 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 sat at 0% CPU, so they were not what heated the Mac, but nothing had told me they were there. Related reports are still open upstream: anthropics/claude-code#1935 and openai/codex#21008.

Killing every process whose parent PID is 1 is unsafe. A background Node job showed a parent PID of 1 after 0.3 s while its agent was still running. Killing by name or by parent PID can kill live work.

tidewake is read-only: it audits the leftovers, shows the commands you could run and executes nothing. AgentDust records ownership while the agent runs, through the agent's hooks, and classifies each process. In the manual flow, I approve cleanup with a 4-character code that AgentDust generates, and it accepts no approval supplied through a model's tool call. Opt-in automatic cleanup uses a directory policy I enable locally and leaves uncertain cases for explicit approval. Before signalling, it checks the process identity again, then sends SIGTERM to that one PID and nothing else. The hook adds a median of 2.5 ms per event on a macos-15 runner.

Security and privacy

True of the code today:

• The release binary imports no socket calls, and the dependency tree has no networking crates.
• The journal keeps session_id and tool_use_id as supplied. It stores keyed digests of the working directory and new subagent IDs, never their raw values. Older version 1 records may contain raw subagent IDs. The digests use an HMAC under a random secret that stays in the data directory. A privacy test runs six hook events whose payloads carry sentinels in the command, a 5 MB response, the working directory, subagent ID and type, transcript paths, an unknown field and the environment, then reads every byte of every file in the data directory (secret, maintenance lock, journal and rotated copies) and every file the run left in the system temp directory. Only the session id may appear, and a journal key outside one list in the code fails the test. Another test sends a 9 MB tool response through the hook and checks that neither the output nor the command reaches the journal.
• setup never edits a symlinked, hard-linked or non-regular settings.json, writes the file by rename with its mode kept and no backup copy, removes only entries its manifest says it created and whose value still matches, and trusts the claude CLI only after claude mcp get shows the exact registration.
• The hook exits 0 and prints nothing, including on malformed input, an unwritable data directory and a data directory on a filesystem that the platform does not support, where it records nothing. Linux journal writes require writable ext4.
• The journal decoder, the journal reader and the hook payload parser are fuzzed beside the KERN_PROCARGS2 parser. Each target runs under a counting allocator and fails when memory is not bounded by the input or by what the call kept, and the decoder target checks that a record appended after any bytes is read. The seeds are replayed by the test suite and by the Linux CI job, and property tests check that a short write costs the record it cut and no other.
• The live tests start real processes (some ignore SIGTERM, some detach into their own session, some outlive their parent) through a harness that can only signal processes it started. It revalidates each one's identity before every signal and logs each signal sent.
• The classifier is checked against a corpus of 22 fixtures that carry the truth about each process: left behind by an ended session, live, detached, managed or unknown. It includes protected cases such as PID 1, another user, the agent itself, launchd and systemd services, a Homebrew service and an app helper. The fixtures that can be started are started for real through the harness, and each one's parent, session and liveness are checked against the kernel.

Cleanup controls:

• Manual cleanup requires a code typed by you. Automatic cleanup requires an enabled local directory policy and freshly proven ended-session ownership. Suspects always require per-item typed approval.
• Each process is classified and its identity read again immediately before the signal.
• The only action is SIGTERM to one PID.

Report a vulnerability privately as described in SECURITY.md.

Using AgentDust 1.8.1

Homebrew targets macOS arm64. npm and release archives support macOS arm64 and Linux x86_64 on Ubuntu 24.04, including Ubuntu 24.04 x86_64 under WSL2. AgentDust supports Claude Code and Codex process tracking, manual and automatic cleanup, TCP port recovery, local cleanup metrics and worker version status. The read-only Claude Code disk report is available on macOS. On Linux and WSL2, the data directory must be on writable ext4. In WSL2, the agent and AgentDust must run in the same distribution. The exact 1.7.1 Linux archive and npm package passed WSL2 release acceptance before publication. The 1.8.1 release workflow repeats the check on its exact artifacts. Automatic cleanup registers a systemd user service. For Codex desktop sessions, automatic cleanup waits until every recorded host process exits. The macOS automatic cleanup acceptance covers normal exit, abrupt exit and worker restart. The M6 lifecycle and attribution scenarios are captured and replayed for Claude Code 2.1.292. Agent Teams remain outside the support claim. See the M6 fixture matrix for tested scenarios and their limits. Use agentdust metrics for totals or agentdust metrics --json for daily buckets; agents can read the same summary with agentdust_metrics (scope and limits).

Install and connect

Install the prebuilt binary and connect it to Claude Code:

brew install hamzahamidi/agentdust/agentdust
agentdust setup

brew install installs the prebuilt binary. To verify the release artifacts, follow these steps. agentdust setup shows a diff and asks before it changes anything (details).

Install the npm package on macOS arm64, Ubuntu 24.04 x86_64 or Ubuntu 24.04 x86_64 under WSL2:

npm install -g agentdust
agentdust setup

The package contains the two native binaries and a small Node launcher, plus the README and license. It has no dependencies or install scripts. Installation does not register hooks or enable cleanup. Run agentdust setup codex to connect Codex, then review its hooks in Codex /hooks.

Use a global installation for hooks, MCP registration and the background worker. npx cache paths and project-local installs are not supported for persistent setup. Upgrading with npm install -g agentdust@latest keeps registrations valid within the same npm prefix. If a Node version manager changes that prefix, first pause automatic cleanup and remove each agent's setup from the old installation. Install under the new prefix, run setup for each agent again, review Codex hook trust, and run agentdust auto resume if cleanup was enabled. Choose one installation channel so the command and registered binary resolve to the same installation.

To uninstall an npm installation, run agentdust auto disable, remove setup for each connected agent (agentdust setup --remove and agentdust setup codex --remove), then run npm uninstall -g agentdust. The data directory stays until you delete it.

Add the optional Claude Code skill

The MCP server exposes the tools. The optional plugin adds /agentdust:cleanup for processes and /agentdust:disk for read-only disk usage. It does not install the server or start cleanup by itself.

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

Start a new Claude Code session, then run /agentdust:cleanup or ask Claude to inspect processes left by a Claude Code session. agentdust_doctor only reads the inventory. When you ask to clean up, the skill creates a fresh plan, shows its eligible items and evidence, then calls agentdust_apply to show AgentDust's typed approval form. Type the generated code yourself to approve. The skill never supplies an approval code. The plugin contains these two skills; agentdust setup separately registers the MCP server and hooks.

The plugin can also be reviewed or tested from a checkout of this repository with claude plugin validate .. See Claude Code plugin installation for install scopes and management.

Find leftover processes

agentdust doctor lists the processes that look left behind by an agent session, each with a class and the evidence for it. agentdust doctor --json prints the same report as JSON. Neither changes anything.

| Class | Meaning | Can AgentDust signal it | | --- | --- | --- | | owned-ended | Started by an agent session that has ended | Yes, with one code for the batch, or automatically within enabled directory policy | | suspect | Its parent is init or its launcher chain is dead, same user, old, idle and not managed | Yes, with one code per process | | owned-live | Started by a session that is still running | Never | | managed | A launchd or systemd service, a Homebrew service, a helper of a running app, or on the deny list | Never | | unknown | Everything else | Never |

You can also ask the agent. Claude Code calls the agentdust_doctor tool and reports what it finds. The findings hold the class, the program name, the PID, the age and the kinds of evidence, and no command text or path.

Clean up with your approval

Through the agent: ask Claude Code to clean up leftover processes. It calls agentdust_plan, which keeps only owned-ended and suspect processes, then agentdust_apply, which shows a form in Claude Code. The form lists the processes and a 4-character code that AgentDust generated. Type the code to approve. There is one code for the whole batch of owned-ended processes and one code per suspect, shown with its evidence. A call covers at most 10 items. A wrong or empty code, a decline, a cancel, and two minutes without an answer end the approval, and nothing is signalled. If the client cannot show the form, agentdust_apply returns apply_not_supported and points to the terminal command.

In a terminal: run agentdust apply. It runs the same steps in one process under the same rules. It refuses unless stdin, stdout and /dev/tty are terminals, the process is in the terminal's foreground, and no ancestor is a known agent, so run it from a terminal window that is not inside an agent. No flag or environment variable supplies a code.

Before each approved process is signalled, AgentDust classifies it again and compares boot session, PID, start time, user and executable path. It then sends SIGTERM to that one PID. It sends no other signal and never signals a process group. It waits up to 5 seconds and reports the process as terminated, a survivor, gone before the signal, or failed revalidation.

Automatically clean proven leftovers

Automatic cleanup requires 1.1.0 or newer. Enable exact directories where you start Claude Code from your own foreground terminal:

agentdust version
agentdust auto enable /absolute/path/to/project /absolute/path/to/another-project
agentdust auto status

Review the directory scopes and type ENABLE once for the batch (binary 1.2.0 or newer). The local worker continues after normal or abrupt Claude Code exit. It signals only freshly proven owned-ended helpers belonging exclusively to an ended session in enabled scope. Kept, live, shared across sessions and uncertain cases remain untouched. Uncertain cases use the manual approval flow above.

agentdust_auto_status lets Claude explain worker state, recent outcomes and approval-required items. MCP status is read-only. With binary 1.2.0 or newer, a local AI agent can enable a user-authorized batch through agentdust auto enable --yes --projects /absolute/path/to/projects. This selects the parent and its immediate Git project directories, without recursive permission. The flag does not approve uncertain processes or remove keeps. Use agentdust auto keep PID for an intentional helper, agentdust auto pause to pause, agentdust auto resume to resume, or agentdust auto disable to clear permissions and remove the worker. See commands, restart behavior and limits.

Check, pause and remove

agentdust status shows the version, the data directory, the journal counters, whether setup is installed and whether apply is enabled. To turn cleanup off and keep everything else, put apply = false in config.toml in the data directory (~/Library/Application Support/agentdust). Before disconnecting Claude Code, run agentdust auto disable to remove the separately installed worker, then agentdust setup --remove and brew uninstall agentdust. The data directory stays until you delete it. If a release is withdrawn, see SECURITY.md and docs/release.md.

Setting up Claude Code

agentdust setup
agentdust status

setup prints a diff of settings.json and the claude mcp add command it will run, then asks before it writes anything (--yes approves without asking). It adds six hook entries for session start and end, subagent start and stop, and Bash tool start and end. It also registers the MCP server agentdust. It records what it added in a manifest, so agentdust setup --remove deletes only that, and agentdust setup --check exits 1 when the installation is missing or was modified. It does not edit a symlinked settings.json. A failed step is rolled back and the report says what was undone. The details are in docs/m3/setup.md.

Running the development probe

Run the probe to check whether your agent client can collect a typed approval. It shows a typed-code form and reports how the client answered. It changes nothing on your machine. Building it needs Rust 1.99.0 (pinned in rust-toolchain.toml); the release candidate is a prebuilt binary that needs no Rust.

cargo build --release

Register it with the agent you use:

claude mcp add --scope user agentdust-probe -- "$PWD/target/release/agentdust" mcp

codex mcp add agentdust-probe "$PWD/target/release/agentdust" mcp

Ask the agent to call agentdust_probe_approval. The tool returns JSON such as {"outcome": "approved", "protocol": "2025-06-18", "path": "legacy"}. Remove the probe afterwards with claude mcp remove --scope user agentdust-probe or codex mcp remove agentdust-probe.

What has been checked, per client (client matrix):

• Codex CLI 0.156.1: the full typed-code flow, including a wrong code, Esc and a timeout.
• Claude Code 2.1.289: the full typed-code form was tested, including accept, wrong code, decline, cancel, timeout and a forged retry. No automatic approval was observed.
• Cursor: not tested.

Licence

MIT