npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

bgproc

v0.3.0

Published

Simple process manager for agents

Downloads

8,692

Readme

bgproc

Simple process manager for agents.

Manage background processes like dev servers from the command line. Designed to be agent-friendly with JSON output and easy status checking.

Install

npm install -g bgproc
# or using npx
npx bgproc start -n myserver -- npm run dev

Usage

# Start a process
bgproc start -n myserver -- npm run dev

# Start and wait for port to be detected (great for dev servers)
bgproc start -n myserver -w -- npm run dev
# Streams logs to stderr, prints JSON with port to stdout when ready

# Force restart (kills existing process with same name)
bgproc start -n myserver -f -w -- npm run dev

# Restart with same command and cwd
bgproc restart myserver
bgproc restart myserver -w  # wait for port

# Check status (returns JSON with port detection)
bgproc status myserver
# {"name":"myserver","pid":12345,"running":true,"port":3000,...}

# View logs
bgproc logs myserver
bgproc logs myserver --tail 50
bgproc logs myserver --follow
bgproc logs myserver --errors  # stderr only

# List all processes
bgproc list
bgproc list --cwd              # filter to current directory
bgproc list --cwd /path/to/dir # filter to specific directory

# Stop a process
bgproc stop myserver
bgproc stop myserver --force   # SIGKILL

# Clean up dead processes
bgproc clean myserver
bgproc clean --all

Features

  • JSON output: All commands output JSON to stdout, errors to stderr
  • Port detection: Automatically detects listening ports via lsof (checks child processes too)
  • Wait for port: --wait-for-port blocks until port is detected, streaming logs
  • Restart: restart re-runs a process with the same command and cwd
  • Force restart: --force kills existing process with same name before starting
  • Duplicate prevention: Prevents starting multiple processes with the same name
  • Log management: Stdout/stderr captured, capped at 1MB
  • Timeout support: --timeout 60 kills after N seconds
  • Auto-cleanup: Starting a process with the same name as a dead one auto-cleans it
  • CWD filtering: Filter process list by working directory

Options

start

-n, --name          Process name (required)
-f, --force         Kill existing process with same name before starting
-t, --timeout       Kill after N seconds
-w, --wait-for-port Wait for port detection (optional: timeout in seconds)
    --keep          Keep process running on wait timeout (default: kill)

restart

-w, --wait-for-port Wait for port detection (optional: timeout in seconds)
    --keep          Keep process running on wait timeout (default: kill)

status, stop, logs, clean

All accept process name as positional arg or -n:

bgproc status myserver
bgproc status -n myserver  # equivalent

logs

-t, --tail     Number of lines (default: 100)
-f, --follow   Tail the log
-e, --errors   Show stderr only
-a, --all      Show all logs

stop

-f, --force    Use SIGKILL instead of SIGTERM

list

-c, --cwd      Filter by directory (no arg = current dir)

clean

-a, --all      Clean all dead processes

Environment

  • BGPROC_DATA_DIR: Override data directory (default: ~/.local/share/bgproc)

Usage with AI Agents

Just ask the agent

The simplest approach - just tell your agent to use it:

Use bgproc to start and manage the dev server. Run bgproc --help to see available commands.

AI Coding Assistants

Add the skill to your AI coding assistant for richer context:

npx skills add ascorbic/bgproc

This works with Claude Code, Cursor, Codex, and other AI coding tools.

AGENTS.md / CLAUDE.md

For more consistent results, add to your project instructions:

## Background Processes

Use `bgproc` to manage dev servers and background processes. All commands output JSON.

Workflow:
1. `bgproc start -n devserver -- npm run dev` - Start a process
2. `bgproc status devserver` - Check if running, get port
3. `bgproc restart devserver` - Restart with same command
4. `bgproc logs devserver` - View output if something's wrong
5. `bgproc stop devserver` - Stop when done

Platform Support

macOS and Linux only. Windows is not supported.

License

MIT © Matt Kane 2026