{"_id":"bgproc","_rev":"4-fa0bd8f28e73bc78a16e7abde30f37cf","name":"bgproc","dist-tags":{"latest":"0.3.0"},"versions":{"0.0.0":{"name":"bgproc","version":"0.0.0","keywords":["background","cli","dev-server","process"],"author":{"name":"Matt Kane"},"license":"MIT","_id":"bgproc@0.0.0","maintainers":[{"name":"ascorbic","email":"m@mk.gg"}],"homepage":"https://github.com/ascorbic/bgproc#readme","bugs":{"url":"https://github.com/ascorbic/bgproc/issues"},"bin":{"bgproc":"dist/cli.mjs"},"dist":{"shasum":"8037fac397804151192ebf626f93c4e7d2ceb303","tarball":"https://registry.npmjs.org/bgproc/-/bgproc-0.0.0.tgz","fileCount":5,"integrity":"sha512-3M99tKOR3lqiqYe2E829+LHv0c3mTnG3pZnhdV4cKWEAk6pXmhrkKn4/76sZVI4V1JKTxG4vS/d4q4yYceaCCg==","signatures":[{"sig":"MEYCIQCcYKXz+Q6HLVZpFbRQKR0aAlvFhlH2qBsI5SDsDCYyHwIhAMqDoJdev5iD+m1haEWcV8nL16YoFO3gVBi/7NAQOkxM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45815},"type":"module","gitHead":"faebcdb77bf49c90d4f72287611539112d4ef8d5","scripts":{"dev":"tsdown --watch","lint":"oxlint","test":"vitest","build":"tsdown","start":"node dist/cli.mjs","format":"oxfmt","release":"changeset publish","lint:fix":"oxlint --fix","changeset":"changeset"},"_npmUser":{"name":"ascorbic","email":"m@mk.gg"},"repository":{"url":"git+https://github.com/ascorbic/bgproc.git","type":"git"},"_npmVersion":"11.4.2","description":"Simple process manager for agents","directories":{},"_nodeVersion":"24.4.0","dependencies":{"citty":"^0.1.6"},"_hasShrinkwrap":false,"devDependencies":{"oxfmt":"^0.27.0","oxlint":"^1.0.0","tsdown":"^0.20.1","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^22.0.0","@changesets/cli":"^2.29.8","oxlint-tsgolint":"^0.11.3","@changesets/changelog-github":"^0.5.2"},"_npmOperationalInternal":{"tmp":"tmp/bgproc_0.0.0_1769632974979_0.6712913646796272","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"bgproc","version":"0.1.0","keywords":["background","cli","dev-server","process"],"author":{"name":"Matt Kane"},"license":"MIT","_id":"bgproc@0.1.0","maintainers":[{"name":"ascorbic","email":"m@mk.gg"}],"homepage":"https://github.com/ascorbic/bgproc#readme","bugs":{"url":"https://github.com/ascorbic/bgproc/issues"},"bin":{"bgproc":"dist/cli.mjs"},"dist":{"shasum":"e18b9e5f0c38c6c72be649a5b6cbb4103a4c5611","tarball":"https://registry.npmjs.org/bgproc/-/bgproc-0.1.0.tgz","fileCount":5,"integrity":"sha512-Y7E4lSDiYO7htvzYxyhuWJzGB1/bK/+Ve6eScpLlQBvkFW4hy/CK6GiwMZe098YWIEZAqv+TR1rpEXsIoIKxsA==","signatures":[{"sig":"MEQCICaXSbYlrU7bHT/Td5UtqlLvXaQKb+EjmvmjCpeA6JM9AiAvjZZtD6WbKK1e+t4iIYmQFZ8SS44z7JMkb/mznLuPmg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/bgproc@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":49067},"type":"module","_from":"file:bgproc-0.1.0.tgz","scripts":{"dev":"tsdown --watch","lint":"oxlint","test":"vitest","build":"tsdown","start":"node dist/cli.mjs","format":"oxfmt","release":"changeset publish","lint:fix":"oxlint --fix","changeset":"changeset"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6a61d36e-6909-454a-b384-bef0194633e4"}},"_resolved":"/tmp/e6dae273f1769d59eefe2c26ed8e4b52/bgproc-0.1.0.tgz","_integrity":"sha512-Y7E4lSDiYO7htvzYxyhuWJzGB1/bK/+Ve6eScpLlQBvkFW4hy/CK6GiwMZe098YWIEZAqv+TR1rpEXsIoIKxsA==","repository":{"url":"git+https://github.com/ascorbic/bgproc.git","type":"git"},"_npmVersion":"11.6.2","description":"Simple process manager for agents","directories":{},"_nodeVersion":"24.13.0","dependencies":{"citty":"^0.1.6"},"_hasShrinkwrap":false,"devDependencies":{"oxfmt":"^0.27.0","oxlint":"^1.0.0","tsdown":"^0.20.1","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^22.0.0","@changesets/cli":"^2.29.8","oxlint-tsgolint":"^0.11.3","@changesets/changelog-github":"^0.5.2"},"_npmOperationalInternal":{"tmp":"tmp/bgproc_0.1.0_1769635815018_0.5174539409761318","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"bgproc","version":"0.2.0","keywords":["background","cli","dev-server","process"],"author":{"name":"Matt Kane"},"license":"MIT","_id":"bgproc@0.2.0","maintainers":[{"name":"ascorbic","email":"m@mk.gg"}],"homepage":"https://github.com/ascorbic/bgproc#readme","bugs":{"url":"https://github.com/ascorbic/bgproc/issues"},"bin":{"bgproc":"dist/cli.mjs"},"dist":{"shasum":"edc71bfe6564d1190502e140bae7b245c5feac9f","tarball":"https://registry.npmjs.org/bgproc/-/bgproc-0.2.0.tgz","fileCount":5,"integrity":"sha512-kBlr0b7PXwde2PmF21g2+i7NJW+pnF2iq5REaJK0uNMNE4iRp0188dG7MaP2Q4qYxJh2VgyB6MGnshGwZ7Aw2A==","signatures":[{"sig":"MEQCIGzVgytjC8x9ncDA2oXDYhDjFtOPBC1yclRR3PlA1j3gAiAOunIK2gFqCrNPFKfUKxGaGGGS30tBYDB4Cn8NHtMR4g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/bgproc@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":56468},"type":"module","_from":"file:bgproc-0.2.0.tgz","scripts":{"dev":"tsdown --watch","lint":"oxlint","test":"vitest","build":"tsdown","start":"node dist/cli.mjs","format":"oxfmt","release":"changeset publish","lint:fix":"oxlint --fix","changeset":"changeset"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6a61d36e-6909-454a-b384-bef0194633e4"}},"_resolved":"/tmp/b15f7ef301eef5fec20679e415b60835/bgproc-0.2.0.tgz","_integrity":"sha512-kBlr0b7PXwde2PmF21g2+i7NJW+pnF2iq5REaJK0uNMNE4iRp0188dG7MaP2Q4qYxJh2VgyB6MGnshGwZ7Aw2A==","repository":{"url":"git+https://github.com/ascorbic/bgproc.git","type":"git"},"_npmVersion":"11.6.2","description":"Simple process manager for agents","directories":{},"_nodeVersion":"24.13.0","dependencies":{"citty":"^0.1.6"},"_hasShrinkwrap":false,"devDependencies":{"oxfmt":"^0.27.0","oxlint":"^1.0.0","tsdown":"^0.20.1","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^22.0.0","@changesets/cli":"^2.29.8","oxlint-tsgolint":"^0.11.3","@changesets/changelog-github":"^0.5.2"},"_npmOperationalInternal":{"tmp":"tmp/bgproc_0.2.0_1769674638762_0.03256996948797619","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"bgproc","version":"0.3.0","description":"Simple process manager for agents","keywords":["background","cli","dev-server","process"],"license":"MIT","author":{"name":"Matt Kane"},"repository":{"type":"git","url":"git+https://github.com/ascorbic/bgproc.git"},"homepage":"https://github.com/ascorbic/bgproc#readme","bugs":{"url":"https://github.com/ascorbic/bgproc/issues"},"bin":{"bgproc":"dist/cli.mjs"},"type":"module","dependencies":{"citty":"^0.1.6"},"devDependencies":{"@changesets/changelog-github":"^0.5.2","@changesets/cli":"^2.29.8","@types/node":"^22.0.0","oxfmt":"^0.27.0","oxlint":"^1.0.0","oxlint-tsgolint":"^0.11.3","tsdown":"^0.20.1","typescript":"^5.9.3","vitest":"^4.0.18"},"scripts":{"build":"tsdown","dev":"tsdown --watch","format":"oxfmt","lint":"oxlint","lint:fix":"oxlint --fix","start":"node dist/cli.mjs","test":"vitest","changeset":"changeset","release":"changeset publish"},"_id":"bgproc@0.3.0","_integrity":"sha512-UHwNISwxVEQtxt8bWNuirzYkliKry5ABcCFHOKE6580Bpil/E9lx/7T3fJhXK84kVviRl5bUD4M6sALYQLAD0A==","_resolved":"/tmp/bea0576e90ff369185035ace6a5b5994/bgproc-0.3.0.tgz","_from":"file:bgproc-0.3.0.tgz","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-UHwNISwxVEQtxt8bWNuirzYkliKry5ABcCFHOKE6580Bpil/E9lx/7T3fJhXK84kVviRl5bUD4M6sALYQLAD0A==","shasum":"b3d5e88bb037b7a1233bd91b271de9abb3f7767a","tarball":"https://registry.npmjs.org/bgproc/-/bgproc-0.3.0.tgz","fileCount":5,"unpackedSize":62068,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/bgproc@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD289uvO5Oj+/nwmped0IVnCFcDsx5/TfoPoEjahVhtogIhAOpG7qsnCXokrSqz5X0GswmDJLOlzE/Q5l+q+KRi1mO2"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6a61d36e-6909-454a-b384-bef0194633e4"}},"directories":{},"maintainers":[{"name":"ascorbic","email":"m@mk.gg"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bgproc_0.3.0_1773251949747_0.4928505880592793"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-28T20:42:54.978Z","modified":"2026-03-11T17:59:10.205Z","0.0.0":"2026-01-28T20:42:55.128Z","0.1.0":"2026-01-28T21:30:15.187Z","0.2.0":"2026-01-29T08:17:18.893Z","0.3.0":"2026-03-11T17:59:09.909Z"},"bugs":{"url":"https://github.com/ascorbic/bgproc/issues"},"author":{"name":"Matt Kane"},"license":"MIT","homepage":"https://github.com/ascorbic/bgproc#readme","keywords":["background","cli","dev-server","process"],"repository":{"type":"git","url":"git+https://github.com/ascorbic/bgproc.git"},"description":"Simple process manager for agents","maintainers":[{"name":"ascorbic","email":"m@mk.gg"}],"readme":"# bgproc\n\nSimple process manager for agents.\n\nManage background processes like dev servers from the command line. Designed to be agent-friendly with JSON output and easy status checking.\n\n## Install\n\n```bash\nnpm install -g bgproc\n# or using npx\nnpx bgproc start -n myserver -- npm run dev\n```\n\n## Usage\n\n```bash\n# Start a process\nbgproc start -n myserver -- npm run dev\n\n# Start and wait for port to be detected (great for dev servers)\nbgproc start -n myserver -w -- npm run dev\n# Streams logs to stderr, prints JSON with port to stdout when ready\n\n# Force restart (kills existing process with same name)\nbgproc start -n myserver -f -w -- npm run dev\n\n# Restart with same command and cwd\nbgproc restart myserver\nbgproc restart myserver -w  # wait for port\n\n# Check status (returns JSON with port detection)\nbgproc status myserver\n# {\"name\":\"myserver\",\"pid\":12345,\"running\":true,\"port\":3000,...}\n\n# View logs\nbgproc logs myserver\nbgproc logs myserver --tail 50\nbgproc logs myserver --follow\nbgproc logs myserver --errors  # stderr only\n\n# List all processes\nbgproc list\nbgproc list --cwd              # filter to current directory\nbgproc list --cwd /path/to/dir # filter to specific directory\n\n# Stop a process\nbgproc stop myserver\nbgproc stop myserver --force   # SIGKILL\n\n# Clean up dead processes\nbgproc clean myserver\nbgproc clean --all\n```\n\n## Features\n\n- **JSON output**: All commands output JSON to stdout, errors to stderr\n- **Port detection**: Automatically detects listening ports via `lsof` (checks child processes too)\n- **Wait for port**: `--wait-for-port` blocks until port is detected, streaming logs\n- **Restart**: `restart` re-runs a process with the same command and cwd\n- **Force restart**: `--force` kills existing process with same name before starting\n- **Duplicate prevention**: Prevents starting multiple processes with the same name\n- **Log management**: Stdout/stderr captured, capped at 1MB\n- **Timeout support**: `--timeout 60` kills after N seconds\n- **Auto-cleanup**: Starting a process with the same name as a dead one auto-cleans it\n- **CWD filtering**: Filter process list by working directory\n\n## Options\n\n### `start`\n\n```\n-n, --name          Process name (required)\n-f, --force         Kill existing process with same name before starting\n-t, --timeout       Kill after N seconds\n-w, --wait-for-port Wait for port detection (optional: timeout in seconds)\n    --keep          Keep process running on wait timeout (default: kill)\n```\n\n### `restart`\n\n```\n-w, --wait-for-port Wait for port detection (optional: timeout in seconds)\n    --keep          Keep process running on wait timeout (default: kill)\n```\n\n### `status`, `stop`, `logs`, `clean`\n\nAll accept process name as positional arg or `-n`:\n\n```bash\nbgproc status myserver\nbgproc status -n myserver  # equivalent\n```\n\n### `logs`\n\n```\n-t, --tail     Number of lines (default: 100)\n-f, --follow   Tail the log\n-e, --errors   Show stderr only\n-a, --all      Show all logs\n```\n\n### `stop`\n\n```\n-f, --force    Use SIGKILL instead of SIGTERM\n```\n\n### `list`\n\n```\n-c, --cwd      Filter by directory (no arg = current dir)\n```\n\n### `clean`\n\n```\n-a, --all      Clean all dead processes\n```\n\n## Environment\n\n- `BGPROC_DATA_DIR`: Override data directory (default: `~/.local/share/bgproc`)\n\n## Usage with AI Agents\n\n### Just ask the agent\n\nThe simplest approach - just tell your agent to use it:\n\n```\nUse bgproc to start and manage the dev server. Run bgproc --help to see available commands.\n```\n\n### AI Coding Assistants\n\nAdd the skill to your AI coding assistant for richer context:\n\n```bash\nnpx skills add ascorbic/bgproc\n```\n\nThis works with Claude Code, Cursor, Codex, and other AI coding tools.\n\n### AGENTS.md / CLAUDE.md\n\nFor more consistent results, add to your project instructions:\n\n```markdown\n## Background Processes\n\nUse `bgproc` to manage dev servers and background processes. All commands output JSON.\n\nWorkflow:\n1. `bgproc start -n devserver -- npm run dev` - Start a process\n2. `bgproc status devserver` - Check if running, get port\n3. `bgproc restart devserver` - Restart with same command\n4. `bgproc logs devserver` - View output if something's wrong\n5. `bgproc stop devserver` - Stop when done\n```\n\n## Platform Support\n\nmacOS and Linux only. Windows is not supported.\n\n## License\n\nMIT © Matt Kane 2026\n","readmeFilename":"README.md"}