# Running Background Tasks

> Starts a long-running process (dev server, watcher) or a slow one-shot job (big install/build) without blocking the turn, and checks on it later. Use whenever a shell command wouldn't finish quickly on its own.

- Skill: `aaravriyer193/running-background-tasks` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aaravriyer193/running-background-tasks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aaravriyer193/running-background-tasks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aaravriyer193 (https://skillmd.com/u/aaravriyer193)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aaravriyer193/running-background-tasks

---


# Running background tasks

A foreground shell call is capped at 60s — anything slower needs `background: true`.

**Servers/watchers (never finish on their own):**
```
shell: npm run dev    (background: true)
```
This returns a `task_id` (e.g. `bg_abc123`). Immediately follow with `open_port` on the port it listens on — that's how the user actually sees it.

**Slow one-shot jobs (installs, builds, long scripts):**
```
shell: npm install    (background: true)
```
Then check on it instead of guessing how long it'll take:
```
wait_task: { "task_id": "bg_abc123" }
```
`wait_task` blocks (up to its own timeout, default 60s) and returns the exit code plus recent output once it's done. If it's still running, call `wait_task` again — don't poll with repeated plain `shell` commands against the log file, that's what this tool is for.

Don't background something that genuinely finishes in a few seconds — plain `shell` is simpler and the result comes back immediately.