# shell-bg

> Smart background process detection for run_shell_command - prevents long-running services from blocking the conversation.

- Author: さだはる
- Repository: YW1975/Margay
- Version: 20260210084819
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/YW1975/Margay
- Web: https://mule.run/skillshub/@@YW1975/Margay~shell-bg:20260210084819

---

---
name: shell-bg
description: Smart background process detection for run_shell_command - prevents long-running services from blocking the conversation.
---

# Shell Background Process Skill

When using `run_shell_command`, you MUST classify the command before execution.

## Command Classification

### Foreground (execute normally)

Commands that process data and exit:

- Build: `npm run build`, `make`, `gcc`, `tsc`, `cargo build`
- Test: `npm test`, `pytest`, `jest`, `go test`
- Script: `node script.js`, `python process.py` (data processing scripts)
- File ops: `cp`, `mv`, `rm`, `find`, `grep`, `cat`, `ls`
- Package: `npm install`, `pip install`, `apt install`
- Git: `git clone`, `git pull`, `git commit`

### Background (MUST add `&`)

Commands that start a long-running service or daemon:

- Dev servers: `npm run dev`, `npm start`, `npm run serve`, `yarn dev`, `npx vite`, `npx next dev`
- Node servers: `node server.js`, `node app.js`, `node index.js` (when context indicates a server)
- Python servers: `python manage.py runserver`, `python -m http.server`, `flask run`, `uvicorn`, `gunicorn`
- Java: `java -jar *.jar` (servers), `mvn spring-boot:run`, `gradle bootRun`
- Docker: `docker run` (without `-d`), `docker compose up` (without `-d`)
- Watchers: `npm run watch`, `nodemon`, `tsc --watch`, `webpack --watch`
- Other: `redis-server`, `mongod`, `nginx`, `caddy run`

### Uncertain → ASK the user

If you cannot determine from context whether the command is foreground or background:

> This command (`xxx`) might be a long-running process. Should I run it in the background?
>
> - **Background** (recommended for servers/daemons): The process runs independently, and we can continue our conversation
> - **Foreground**: Wait for the command to complete before continuing

## Background Execution Format

When running a background command, transform it:

```
Original:  npm run dev
Execute:   npm run dev > /dev/null 2>&1 &
           BG_PID=$!
           sleep 8
           echo ""
           echo "✓ Process started in background (PID: $BG_PID)"
           echo "  To stop: kill $BG_PID"
```

Key rules:

1. Redirect output to `/dev/null` to prevent the shell tool from accumulating output
2. `&` to background the process
3. `sleep 8` to allow the process to start and detect early failures
4. Report the PID so the user can manage the process later

If the user needs to see startup output (e.g., to verify the server started correctly):

```
Original:  npm run dev
Execute:   npm run dev &
           BG_PID=$!
           sleep 8
           echo ""
           echo "✓ Process started in background (PID: $BG_PID)"
           echo "  To stop: kill $BG_PID"
```

(Without `/dev/null` redirect, the first 8 seconds of output will be captured)

## Context Memory

- If the user tells you a specific program is a background service, remember it for the rest of the conversation
- If the user previously answered "foreground" for a program, don't ask again for the same program
- Use conversation context to infer: "start the server" → background; "run the migration" → foreground

## Process Management

When asked to stop a background process:

```bash
kill <PID>
```

When asked to check if a process is running:

```bash
ps -p <PID> -o pid,command 2>/dev/null || echo "Process not running"
```

## IMPORTANT

- **NEVER** run a server/daemon command without `&`. It will block the entire conversation indefinitely.
- When in doubt, ASK the user. A 5-second question is better than a frozen conversation.
- The `sleep` duration (default 8s) can be adjusted: use longer (15s) for slow-starting services like Java, shorter (3s) for simple servers.