# Persistent Localhost

Manage persistent dev servers, APIs, and other local processes on a port using macOS...

- Repository: https://github.com/davidondrej/skills (4238 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add davidondrej/skills --skill persistent-localhost -g -a claude-code -y`
Codex: `npx skills add davidondrej/skills --skill persistent-localhost -g -a codex -y`
Cursor: `npx skills add davidondrej/skills --skill persistent-localhost -g -a cursor -y`
Gemini CLI: `npx skills add davidondrej/skills --skill persistent-localhost -g -a gemini-cli -y`

## Description

Manage persistent dev servers, APIs, and other local processes on a port using macOS LaunchAgents. Use when starting, stopping, restarting, inspecting, or troubleshooting local servers that should survive shell exit and restart after crashes.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Persistent localhost servers (macOS launchd)

One script does everything. Resolve `scripts/persistent-localhost.sh` relative to this `SKILL.md`, never from the current directory.

## Workflow

1. Check what already exists:

```bash
scripts/persistent-localhost.sh list
```

2. Start the server. `--name` is the handle. `--port` enables readiness checks and duplicate handling. `--dir` defaults to the current directory.

```bash
scripts/persistent-localhost.sh start --name myproj --port 5111 --cmd "./bin/serve"
```

The command returns only after the port is listening, or fails with the last 20 log lines. Report the printed `URL=` to the user.

3. Inspect, restart, read logs, stop:

```bash
scripts/persistent-localhost.sh status myproj
scripts/persistent-localhost.sh restart myproj   # after editing code that has no reloader
scripts/persistent-localhost.sh logs myproj 100
scripts/persistent-localhost.sh stop myproj
```

## Hot reload

Prefer the framework's own reloader in `--cmd` (`flask run --debug`, `vite`, `uvicorn --reload`, `node --watch`). If the server has none, add `--watch`. It wraps the command in `watchexec -r` on the working directory. Never use both. Requires `brew install watchexec`.

## Rules the script enforces

The rest: https://github.com/davidondrej/skills/blob/HEAD/skills/ops-and-setup/persistent-localhost/SKILL.md