ascorbic/bgproc

Overview

This skill is a lightweight TypeScript-based CLI for managing background processes like dev servers. It provides simple start, stop, status, logs, list, and cleanup commands, emitting structured JSON for machine-friendly integration. Use it to run long-lived commands, detect listening ports, and keep logs per process.

How this skill works

bgproc launches commands as named background jobs and tracks their PIDs, stdout/stderr, and listening port where possible. Commands always print JSON to stdout and stream operational logs to stderr while starting. Port detection uses OS utilities (lsof) and inspects child processes on macOS/Linux; logs are rotated and capped per process.

When to use it

• Start a development server or other long-running task reliably in the background.
• Wait for a process to open its HTTP/TCP port before proceeding in a workflow.
• Check whether a named job is running and which port it is listening on.
• Inspect recent stdout/stderr output for debugging without attaching to the process.
• Stop, force-kill, or clean up dead/stale background jobs.

Best practices

• Name each background job uniquely with -n so you can manage it easily later.
• Use -w when starting dev servers to wait for port readiness before continuing.
• Use -f to force-restart only when you intend to replace an existing process.
• Limit log size expectations; logs are capped at ~1MB per process—stream essential output.
• Filter list by cwd when multiple projects share the same machine to avoid confusion.

Example use cases

• Start a web dev server and wait for its port: bgproc start -n dev -w -- npm run dev.
• Run a background worker and retrieve its status: bgproc start -n worker -- node worker.js; bgproc status worker.
• Tail errors only to diagnose a failing service: bgproc logs api --errors --tail 200.
• Clean up dead entries after a crash: bgproc clean --all.
• Force-redeploy a local service: bgproc start -n api -f -w -- npm run dev.