⚙️ Procx — Modern Process & Port Management CLI & API

Procx is a fast, cross-platform command-line tool and Node.js library for managing, inspecting, and controlling system processes and network ports. Built for developers who need reliable process management across macOS, Linux, and Windows.

Think of it as a modern, developer-friendly replacement for ps, kill, netstat, and lsof — all unified in one powerful tool with both CLI and programmatic interfaces.

Key Features

• Process Discovery: Find processes by port, PID, or name with detailed information
• Safe Termination: Kill processes gracefully or forcefully with confirmation prompts
• Port Management: List active ports, find free ports, and resolve conflicts automatically
• System Monitoring: Real-time process monitoring with CPU, memory, and resource tracking
• Smart Filtering: Filter and sort processes by various criteria
• Cross-Platform: Native support for macOS, Linux, and Windows
• Programmatic API: Full Node.js API for integration into applications and scripts

Installation

CLI Usage (Global)

# Install globally for CLI usage
npm install -g procx

# Or run directly without installation
npx procx <command>

Library Usage (Project)

# Install in your project for programmatic use
npm install procx

Common CLI Examples

Find and Kill Processes

# Find which process is using port 3000
procx find 3000

# Kill process using port 8080 (with confirmation)
procx kill 8080

# Force kill process by PID
procx kill --pid 1234 --force

# Kill all Node.js processes interactively
procx find --name node
procx kill --pid <selected_pid> --interactive

Port Management

# List all active ports and their processes
procx ports

# Find next available port starting from 3000
procx free --start 3000

# Find free port in specific range
procx free --start 8000 --end 8100

# Resolve port conflict and start new server
procx resolve 3000 --run "npm start"

Process Monitoring

# List all running processes
procx list

# Filter processes by name
procx list --filter node

# Sort by CPU usage and limit results
procx list --sort cpu --limit 10

# Monitor processes in real-time
procx monitor

# Monitor with custom refresh interval
procx monitor --interval 5 --filter node

System Information

# Get comprehensive system information
procx sysinfo

# Output system info as JSON
procx sysinfo --json

# Check system resource usage
procx list --sort memory --limit 5

Development Workflows

# Kill development server and restart
procx kill 3000 && npm start

# Find and kill all webpack processes
procx find --name webpack
procx kill --pid <webpack_pid>

# Clean up all Node.js development processes
procx list --filter node --json | jq '.[].pid' | xargs -I {} procx kill --pid {}

# Start server on next available port
PORT=$(procx free --start 3000) npm start

# Monitor resource usage during development
procx monitor --filter "node|webpack|vite"

Basic Library Usage

Quick Start

import { findProcess, killProcess, getFreePort, listProcesses } from 'procx';

// Find process using a specific port
const process = await findProcess({ port: 3000 });
console.log(`Found: ${process.name} (PID: ${process.pid})`);

// Kill a process by PID
await killProcess({ pid: 1234 });

// Find next available port
const freePort = await getFreePort(3000);
console.log(`Available port: ${freePort}`);

// List processes with filtering
const nodeProcesses = await listProcesses({ 
  name: 'node',
  sortBy: 'cpu' 
});

Common Integration Patterns

// Automatic port conflict resolution
import { getFreePort, resolvePortConflict } from 'procx';

// Find free port for your application
const port = await getFreePort(3000);
app.listen(port);

// Or resolve conflicts automatically
await resolvePortConflict(3000, 'npm start');

// Process monitoring in applications
import { startMonitor } from 'procx';

const monitor = startMonitor({ refreshInterval: 5000 });
for await (const processes of monitor) {
  const highCpuProcesses = processes.filter(p => p.cpu > 80);
  if (highCpuProcesses.length > 0) {
    console.warn('High CPU usage detected:', highCpuProcesses);
  }
}

Documentation

Choose your path based on how you want to use Procx:

For CLI Users

Using Procx from the command line to manage processes and ports

• CLI Commands & Examples - Complete command reference with real-world examples
• Installation Guide - Setup instructions for CLI usage
• Troubleshooting - Fix common CLI issues

For Library Users

Integrating Procx into your Node.js applications

• Library Documentation - Complete Node.js API reference and examples
• Installation Guide - Setup instructions for programmatic usage

I Want To...

Get Started

• Install and use CLI commands → CLI Documentation
• Integrate into my Node.js app → Library Documentation

Manage Processes & Ports

• Find what's using a port → CLI Commands - Port Management
• Kill processes safely → CLI Commands - Process Management
• Monitor system resources → CLI Commands - System Monitoring

Develop with Procx

• Use Procx in my code → Library Documentation
• Handle errors properly → Library Documentation - Error Handling

Solve Problems

• Fix installation issues → Troubleshooting
• Get help with commands → CLI Documentation
• Debug API integration → Library Documentation

All Documentation

Core Guides

• CLI Documentation - Complete command reference and examples
• Library Documentation - Node.js API reference and integration
• Installation Guide - Setup for both CLI and library usage
• Troubleshooting - Solutions for common issues

Need Help?

• Installation issues → Troubleshooting
• CLI questions → CLI Documentation
• Library integration → Library Documentation
• Report bugs → GitHub Issues
• Contribute → Contributing Guidelines

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

# Quick setup for contributors
git clone https://github.com/AnuragVikramSingh/procx.git
cd procx
npm install
npm run build
npm run lint

License

MIT License © 2025 Anurag Vikram Singh. See LICENSE for details.

Built for developers who need reliable process management • Documentation • Issues • Contributing