home / skills / petekp / agent-skills / process-hunter

process-hunter skill

safe

This skill helps you identify and terminate resource-hogging processes to reclaim CPU, memory, and battery while providing a clear hunt report.

This is most likely a fork of the process-hunter skill from petekp

npx playbooks add skill petekp/agent-skills --skill process-hunter

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

5.7 KB

---
name: process-hunter
description: >
  CAVEMAN HUNT BAD PROCESS! Me find greedy creature eating fire and rocks.
  Me bonk them good. Use when tribe say "kill processes", "clean up servers",
  "save battery", "find resource hogs", "bonk next.js", or "hunt processes".
  Me bonk known bad creature automatic. Me ask before bonk mystery creature.
---

# 🦣 CAVEMAN PROCESS HUNTER 🦣

Me find greedy process eating all fire (CPU) and hoarding rocks (memory).
Me bonk them. Lightning rock (battery) happy. Tribe proud.

## How Hunt Work

**IMPORTANT:** Always show hunt report after bonking! Tribe need see victory!

1. **Remember before-time** (so can compare later):
   ```bash
   python scripts/measure_power.py before
   ```

2. **Find greedy creature**:
   ```bash
   python scripts/hunt_processes.py
   ```

3. **BONK!** (track how many bonk and how much rock freed)

4. **Show big victory report** - ALWAYS do this after hunt:
   ```bash
   python scripts/measure_power.py report <bonk_count> <rocks_freed_mb>
   ```

## Cave Tools

### hunt_processes.py - Find Bad Creature

```bash
python scripts/hunt_processes.py [--cpu-threshold 10] [--mem-threshold 500]
```

Me sort creature into pile:
- **🦴 BONK NOW**: Me know these bad. Safe smash.
- **🤔 ME NOT SURE**: Mystery creature. Ask human first.

### terminate_process.py - BONK Tool

```bash
python scripts/terminate_process.py <pid> [--force]
```

Me try gentle tap first. If creature no listen, ME USE BIG CLUB.
Use `--force` to skip gentle tap. Go straight to BIG CLUB.

### measure_power.py - Lightning Rock Checker

```bash
python scripts/measure_power.py before    # Remember this moment
python scripts/measure_power.py report    # Show hunt victory
python scripts/measure_power.py status    # Quick peek at juice
```

## Creature Me Know Safe To Bonk

These greedy. These eat much fire. BONK:
- Next.js fire-eater (`next-server`)
- Webpack bundle-beast
- Vite speed-demon
- Turbo thunder-lizard
- npm/yarn/pnpm run-run things
- React Native bridge troll
- Claude brain-in-box (when too many clone)
- TypeScript watcher-eye
- esbuild fast-maker

## When Ask Human First

Use AskUserQuestion before bonk:
- Mystery creature me not recognize
- Human app (browser, picture-maker, code-cave)
- Anything not in bonk-safe list

## Example Hunt

```
    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    ┃  🦣 CAVEMAN PROCESS HUNTER 🦣                    ┃
    ┃  ᕦ(ò_óˇ)ᕤ  Me find greedy process!              ┃
    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

    🦴 BONK NOW! (me know these bad)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      PID  61331 │ Fire: 121.9% 🔥🔥🔥🔥🔥
                  │ Rock: 2886.5MB 🪨🪨🪨🪨🪨
                  │ What: Next.js fire-eater
                  │ Name: next-server
```

## Victory Report

After hunt, always show:

```
    ╔════════════════════════════════════════════════════════╗
    ║     🦣 CAVEMAN HUNT REPORT 🦣                          ║
    ║     ᕦ(ò_óˇ)ᕤ  Me show what happen!                     ║
    ╚════════════════════════════════════════════════════════╝

    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    ┃                    💀💀💀💀💀                    ┃
    ┃                    🏏🏏🏏🏏🏏                    ┃
    ┃                                             ┃
    ┃   Creatures Bonked:   5                      ┃
    ┃   Cave Space Free: ~7.8 big rocks            ┃
    ┃                                             ┃
    ┃   OOGA BOOGA! GOOD HUNT!                    ┃
    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

    ╭────────────────────────────────────────────╮
    │  🦣 MAMMOTH-SIZE VICTORY! 🦣                │
    │                                            │
    │     BEFORE           AFTER                 │
    │    ┌──────┐        ┌──────┐               │
    │    │ 135  │  >>>   │ 212  │   +77 sun     │
    │    └──────┘        └──────┘               │
    │                                            │
    │  ✨ Lightning rock VERY happy! ✨          │
    ╰────────────────────────────────────────────╯

     ╔════════════╗┐
     ║  58%  ⚡  ║│
     ║ [█████░░░░░] ║│
     ╚════════════╝┘

    ⏱️  Sun-moves remaining: 3:32

    ════════════════════════════════════════════════════════
    🌿 Magic lightning box breathe easy now!
    🦴 Caveman did good. Tribe proud.
```

## Caveman Wisdom

- Fire = CPU (how much thinking)
- Rock = Memory (how much cave space)
- Sun-moves = Minutes (time before lightning rock sleep)
- Lightning rock = Battery
- Bonk = Terminate process
- Big club = SIGKILL (force)
- Gentle tap = SIGTERM (nice ask)

Overview

This skill is a command-line process hunter that identifies and optionally terminates resource-hungry processes to free CPU, memory, and battery. It runs safe heuristics to automatically kill known problematic services and prompts for confirmation before terminating unfamiliar processes. The skill also measures power/energy impact before and after a hunt and produces a concise victory report.

How this skill works

The skill uses scripts to measure power usage, scan processes against CPU and memory thresholds, and classify results into 'bonk now' (safe to kill) or 'ask first' (unknown). Termination uses a gentle SIGTERM first and an optional forced SIGKILL when needed. After any bonk, it generates a summary report showing processes terminated, memory reclaimed, and power impact.

When to use it

Free up CPU on overloaded development servers
Reduce memory pressure to avoid out-of-memory issues
Save battery on laptops by killing background build/watch processes
Clean up runaway dev tools (Next.js, Webpack, Vite, etc.)
Before shipping or testing when a clean environment is required

Best practices

Run measure_power.py before a hunt to capture baseline metrics
Use conservative thresholds and review the 'ask first' list before bonking unknown processes
Prefer graceful termination (no --force) and escalate only if processes do not exit
Always run the victory report to record how many processes were terminated and resources freed
Add or remove known-safe bonk targets to match your environment

Example use cases

Developer laptop slows during hot recompile: run the hunter to kill runaway watchers and reporters
CI worker exhausted memory: scan and bonk nonessential build tools to complete jobs
Battery drain during local testing: measure, hunt, and report to verify battery improvements
Automated cleanup on long-lived staging hosts to remove stale dev servers and free resources

FAQ

Which processes will be terminated automatically?

Known development resource hogs (Next.js server, Webpack, Vite, Turbo, package runners, TypeScript watchers, esbuild, common React Native or Claude clones) are classified as safe to bonk and can be terminated automatically.

What happens for processes I don't recognize?

Unknown or ambiguous processes are listed under 'ask first' and require manual confirmation before termination to avoid killing important user apps.

How do I force immediate termination?

Use terminate_process.py <pid> --force to skip the graceful SIGTERM and send SIGKILL (big club). Use with care.