How to clean up after a Claude Code session

Before you exit: /tasks

While the session is still open, type:

/tasks

It lists the background work Claude Code is running in this session, including long-running shell commands such as a dev server or a test watcher. Stop the ones you don’t need from there. This is the easy case, because Claude Code knows about them.

The harder case is what it doesn’t know about: processes those commands forked off, servers started with & or nohup, and containers. The rest of this page finds those.

1. Ports still listening

lsof -nP -iTCP -sTCP:LISTEN | grep -Ev 'ControlCenter|rapportd|sharingd'

Anything on 3000, 5173, 8000 or 8080 that you didn’t start yourself is a likely leftover. For each PID, confirm it belongs to the project the agent was working in:

lsof -a -p <PID> -d cwd -Fn | tail -1

Stop it with kill <PID>. Our kill a process on a port guide covers the stubborn cases.

2. Processes from the project folder

Most dev tools run from node_modules/.bin or a virtualenv inside the project, so the project path is in their command line. From the project folder:

pgrep -lf "$PWD"

That catches watchers that don’t open a port, like tsc --watch, vitest, tailwindcss --watch or esbuild --service. Kill what you don’t need:

pgrep -f "$PWD" | xargs kill

Run the pgrep -lf line first and read the list. If your editor’s language server also runs from that folder, it’ll be in there too.

3. Orphans

When the agent’s shell exits, children it left behind get re-parented to launchd. List dev tools whose parent PID is 1:

pgrep -u "$USER" -P 1 -lf 'node|vite|tsc|python|ruby|bun'

The full method, and how to tell an orphan from a normal app, is in finding orphaned Node processes.

4. Docker containers

Agents often run docker compose up -d for a database. The -d means it runs until someone stops it.

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}\t{{.RunningFor}}'
docker compose down        # in the project folder

5. Things that keep your Mac awake

A leftover dev server rarely blocks sleep on its own, but a caffeinate the agent ran for a long build does, and so can a stuck test browser. Check:

pmset -g assertions | grep -A20 'Listed by owning process'

More on reading that output in why won’t my Mac sleep.

6. Worktrees and branches

If you let the agent work in git worktrees, they stay on disk after the session:

git worktree list
git worktree remove <path>

Make it automatic with a hook

Claude Code runs a SessionEnd hook when a session ends. A small hook can record what was listening at that moment, so you have a list to check next time you sit down. In ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "lsof -nP -iTCP -sTCP:LISTEN > ~/.claude/ports-at-session-end.txt"
          }
        ]
      }
    ]
  }
}

You could make the hook kill things instead, but be careful. Two sessions in the same project share one folder, and an automatic pkill can take down the other session’s server, or your own.

Doing this with Stat Space

Stat Space’s Agents tab watches Claude Code, Codex and Cursor sessions as they run: runtime, CPU, child processes and the ports they open. When a session ends, anything it started that’s still running and has been idle for 10 minutes is flagged as a leftover, with one Clean up button. Leftovers and orphans also light the menu bar attention dot. Nothing is stopped without asking, and system processes are never touched.

From the terminal, statspace agents lists sessions and their leftovers and statspace cleanup <session> stops them. Agents can do it themselves over MCP with the cleanup_agent_leftovers tool, which returns the list and waits for confirmation before killing anything. See the Agents feature and the MCP setup guide.