port-detective

# port-detective

Investigate which process is using a port, identify what started it and what config spawned it, examine what depends on it, and analyze findings to provide actionable recommendations for safely stopping it. Uses system commands to gather info then analyzes the data.

## Installation

This is a CmdForge tool. Install it using:

```bash
cmdforge install port-detective
```

Once installed, it's available as a command-line tool that can be used directly or in Unix pipes.

## Usage

```bash
# Investigate a specific port
port-detective --port 8080

# Check UDP port instead of TCP
port-detective --port 53 --protocol udp

# Investigate port 5432 (PostgreSQL)
port-detective --port 5432

# Check what's using port 3000
port-detective --port 3000 --protocol tcp
```

## Arguments

| Flag | Variable | Default | Description |
|------|----------|---------|-------------|
| `--port` | port | _(required)_ | Port number to investigate |
| `--protocol` | protocol | `tcp` | Protocol to check (tcp or udp) |

## How It Works

This tool follows a 4-step pipeline:

1. **gather_port_info** - Collects initial information about the specified port using system commands (netstat/ss/lsof)
2. **extract_pid** - Extracts the process ID (PID) from the gathered port information
3. **gather_process_info** - Gathers comprehensive process details including parent process, command line, config files, environment variables, and dependencies
4. **analyze_findings** - Uses AI (Claude Sonnet) to analyze all collected data and provide actionable recommendations for safely stopping the process

The tool combines system-level investigation with AI-powered analysis to give you a complete picture of what's using a port and how to safely manage it.

## Dependencies

None - uses standard system utilities (netstat, ss, lsof, ps) available on most Unix-like systems.