Lazyports

Interactive TUI for managing listening ports - the lazy way to kill ports, inspect processes, and manage Docker containers.

🚧 Status: Early Development

This project is in active development. See IMPLEMENTATION_PLAN.md for progress.

Current Status: Checkpoint 9 (Docker Plugin Foundation) - Plugin system operational with Docker integration

Installation

Quick Install (Recommended)

# Using npm
npm install -g lazyports

# Using pnpm
pnpm add -g lazyports

# Using yarn
yarn global add lazyports

After installation, use the lp or lazyports command:

lp              # Launch interactive TUI (if PATH configured)
lazyports       # Alternative command (always works)
lp --help       # Show help
lp ports        # List all ports
lp check 3000   # Check if port 3000 is free

Note: On Linux/Unix, lp conflicts with the system line printer command. If you get /usr/bin/lp exists error or the wrong command, use lazyports instead, or configure your PATH.

One-Line Install Script

curl -fsSL https://raw.githubusercontent.com/ralf-boltshauser/lazyports/main/scripts/install.sh | sh

From Source (Development)

# Clone the repository
git clone https://github.com/ralf-boltshauser/lazyports.git
cd lazyports

# Install dependencies
pnpm install

# Build
pnpm build

# Link globally for development
pnpm link:global

Requirements: Node.js >= 18.0.0

For detailed installation instructions, see INSTALLATION.md.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode
pnpm dev

# Run tests
pnpm test

Features

• ✅ Port Scanning - Cross-platform port detection (macOS, Linux, Windows)
• ✅ Interactive TUI - Terminal UI with keyboard navigation
• ✅ Process Management - Kill processes on ports
• ✅ Process Details - View detailed process information
• ✅ Search & Filter - Fuzzy search and column sorting
• ✅ Plugin System - Extensible architecture for plugins
• ✅ Docker Integration - Automatic Docker container detection and enrichment
• ✅ Project View - Project-aware port view with Docker Compose and framework detection

Documentation

• User Flows - All user flows and features
• Architecture - System architecture
• Tech Stack - Technology choices
• Implementation Plan - Step-by-step development plan
• Plugin System - Plugin development guide
• Docker Plugin - Docker integration

License

MIT