🇨🇳 · 🇬🇧

http-server

GitHub · PyPI

Forget ports. Just preview.

Based on python3 -m http.server, zero external dependencies. Just hs -o to preview your project.

hs is an independent tool — unrelated to the npm package "http-server".

• Zero External Dependencies — Python 3.7+, macOS/Linux/Windows (pip install http-server-cli)
• Auto Port + Smart Index — Default 8080, auto-increment on conflict; auto-open most-recent HTML when no index.html; specify with -i (hs -o)
• Project Management — Track port↔path mapping, monitor CPU/memory, JSON output (hs list)
• Multiple Launch Modes — Daemon or foreground (-d/-f)
• Web Dashboard — hs dashboard -o GUI (CN/EN toggle, 60s countdown, Kill All, error handler)
• AI Agent Integration — hs mcp MCP Server (SSE/stdio, 6 tools), managed infrastructure isolation

Why hs

Multiple frontend projects → constant context switching: "Which port is A on?" "Who's occupying 8080?".

hs closes the loop: Start → Track → List → Kill.

Comparison

Installation

pip install http-server-cli
# or: pip install --upgrade http-server-cli

Verify:

hs version     # → http-server v1.0.x
hs -o        # Start in current directory + open browser

Usage

Daily Workflow

# 1. Preview your project
cd ~/project-alpha
hs -o                     # Auto port + open browser

# 2. Check running servers
hs list
# ✅  http://localhost:8080   →  ~/project-alpha
# ✅  http://localhost:8081   →  ~/project-beta  (daemon)

# 3. Kill unwanted servers
hs kill 8080                # By port
hs kill ~/project-alpha     # By path
hs kill-all                 # Kill all

Start

View

Kill

Bookmark

Dashboard

Managed services (dashboard, MCP SSE) are tracked in registry-managed.json; hs kill-all does NOT stop them.

MCP (AI Agent)

History & Config

Tips

• hs without args = hs start . (start in current directory)
• hs . -i app.html: use app.html as the index page

Data Directory

~/.http-server.cli/
├── config.json            # Default port/domain configuration
├── registry.json          # port → {path, pid, domain, started_at, index_page}
├── registry-managed.json  # Infrastructure services (dashboard, MCP SSE)
└── logs/{port}.log        # http.server logs

Local Development

git clone git@github.com:imjaden/http-server.cli.git
cd http-server.cli
pip install -e .
python3 -m pytest tests/

Is This Reinventing the Wheel?