persistent-localhost
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.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4.3k
- Forks
- 626
01 前言 Front Matter
- name
- persistent-localhost
- 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.
02 资源文件 1
- 脚本scripts/persistent-localhost.sh7.0 KB
03 SKILL.md 正文
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
- Check what already exists:
scripts/persistent-localhost.sh list
- Start the server.
--nameis the handle.--portenables readiness checks and duplicate handling.--dirdefaults to the current directory.
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.
- Inspect, restart, read logs, stop:
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
- Runs as
com.persistent-localhost.<name>in the userguidomain vialaunchctl bootstrap. Restart useskickstart -kp, stop usesbootout. No deprecatedload,start,stop, no broadpkill. KeepAliveonly on crash. A clean exit stays down. Throttle 5s so a syntax error cannot spin.- Port already taken by the same app (our own label, or a stray process with the same working directory) is replaced. A different app is left alone and the next free port is used. Read the printed
PORT=. - The caller's
PATHand aPORTvariable are passed into the job. Add more with--env KEY=VAL. - Logs:
~/Library/Logs/persistent-localhost/<name>.log. State:~/Library/Application Support/persistent-localhost/<name>.state. Plist:~/Library/LaunchAgents/.
Fallback
Never start servers with nohup, &, disown, setsid, or run_in_background. If launchctl bootstrap fails, report the failure and stop.
04 同仓库更多 Skills
varied-search
Research a topic across the web, GitHub, and X/Twitter with DeepAPI and produce a concise Markdown report. Use for varied-search or requests to compare web coverage, relevant repositories, and social discussion.
total-review
Run five independent max-effort reviews (Fable 5.1, Opus 5.5, GPT-6 Astra, GPT-6.1 Sol, Muse Wonder), merge their findings, and fix only what the user approves. Use for /total-review, or when the user or another agent asks for a total review.
stop-overthinking
Manually-invoked skill that stops overthinking and forces a short, practical decision. Use only when the user explicitly invokes stop-overthinking.
state
Manually-invoked skill that recaps what the current thread is doing and how far along it is. Use when the user says "state", "where are we", or "what % are we done".
setup-help
Guide setup one step at a time and show what remains. Use only when the user explicitly asks for it by name.
self-archive
Archive the current Cloudroom thread and release its runtime. Use only when the user explicitly asks to self-archive, archive yourself, or archive this thread.