bgproc

Category: Tools & Productivity | Uploader: ascorbic | Downloads: 0 | Version: v1.0（Latest）

Manage background processes like dev servers. Use when you need to start, stop, or check status of long-running processes.

Changelog: Source: GitHub https://github.com/ascorbic/bgproc

Directory Structure

Current level: Root

📁 .changeset/
- 📄 config.json 307 B
- 📄 README.md 510 B
📁 .github/
- 📁 workflows/
  - 📄 claude-code-review.yml 1.4 KB
  - 📄 claude.yml 1.8 KB
  - 📄 release.yml 1.4 KB
  - 📄 semantic-prs.yml 1.3 KB
  - 📄 test.yml 528 B
📁 .vscode/
- 📄 settings.json 78 B
📁 src/
- 📁 commands/
  - 📄 clean.ts 2.0 KB
  - 📄 list.ts 1.6 KB
  - 📄 logs.ts 2.0 KB
  - 📄 restart.ts 1.8 KB
  - 📄 start.ts 2.5 KB
  - 📄 status.ts 1.3 KB
  - 📄 stop.ts 1.5 KB
- 📄 cli.ts 863 B
- 📄 logs.ts 2.2 KB
- 📄 ports.ts 1.7 KB
- 📄 process.ts 4.4 KB
- 📄 registry.ts 3.0 KB
- 📄 utils.ts 374 B
📁 test/
- 📄 cli.test.ts 12.0 KB
📄 .gitignore 216 B
📄 CHANGELOG.md 2.2 KB
📄 CLAUDE.md 2.0 KB
📄 package.json 1.2 KB
📄 pnpm-lock.yaml 80.5 KB
📄 README.md 4.2 KB
📄 renovate.json 137 B
📄 SKILL.md 2.4 KB
📄 tsconfig.json 1.1 KB
📄 tsdown.config.ts 194 B
📄 vitest.config.ts 120 B

SKILL.md

---
name: bgproc
description: Manage background processes like dev servers. Use when you need to start, stop, or check status of long-running processes.
---

# bgproc

A CLI for managing background processes. All commands output JSON to stdout.

## When to Use

Use bgproc when you need to:
- Start a dev server or other long-running process in the background
- Restart a process with the same command and working directory
- Check if a process is running and what port it's listening on
- View logs from a background process
- Stop a background process

## Commands

```bash
# Start a process
bgproc start -n <name> -- <command...>
bgproc start -n devserver -- npm run dev
bgproc start -n devserver -t 300 -- npm run dev  # auto-kill after 5 min

# Start and wait for port (recommended for dev servers)
bgproc start -n devserver -w -- npm run dev      # wait for port, then exit
bgproc start -n devserver -w 30 -- npm run dev   # wait up to 30s for port

# Force restart (kill existing process first)
bgproc start -n devserver -f -w -- npm run dev

# Restart with same command and cwd (kills if running)
bgproc restart <name>
bgproc restart <name> -w      # wait for port after restart

# Check status (returns JSON with pid, running state, port)
bgproc status <name>

# View logs
bgproc logs <name>
bgproc logs <name> --tail 50
bgproc logs <name> --errors  # stderr only

# List all processes
bgproc list
bgproc list --cwd  # filter to current directory

# Stop a process
bgproc stop <name>
bgproc stop <name> --force  # SIGKILL

# Clean up dead processes
bgproc clean <name>
bgproc clean --all
```

## Workflow

1. Start a process and wait for port: `bgproc start -n devserver -w -- npm run dev`
   - Streams logs to stderr while starting
   - Prints JSON with port to stdout when ready
   - Use `-f` to force restart if already running
2. Restart a process: `bgproc restart devserver -w`
   - Re-runs with the same command and cwd
   - Kills the process first if still running
3. If something's wrong, check logs: `bgproc logs devserver`
4. When done: `bgproc stop devserver`

## Notes

- All commands output JSON to stdout, errors to stderr
- Port detection works via `lsof` and checks child processes (macOS/Linux only)
- Use `-w` to wait for port detection before returning
- Use `-f` to force restart (kills existing process with same name)
- Starting a process with the same name as a dead one auto-cleans it
- Logs are capped at 1MB per process

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

bgproc

Directory Structure

SKILL.md

Report

Notice