# Background Terminals

> Run and manage long-lived shell commands in background terminals. Use for dev servers, watchers, streaming builds, and other commands that should keep running while the agent continues working.

- Skill: `jal-co/background-terminals` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jal-co/background-terminals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jal-co/background-terminals/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jal-co (https://skillmd.com/u/jal-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jal-co/background-terminals

---


# Background Terminals

Use `bg_start` for long-running commands; use regular `bash` for quick commands.

## Start

Call `bg_start` with:

- `command`: shell command to run
- `title`: short recognizable label
- `working_dir`: project directory when different from the current directory

Background commands receive no stdin. Never use them for interactive prompts.

After starting, continue useful work instead of polling. The terminal sends one completion message when it exits.

## Inspect and stop

- Use `bg_status` only when current output or status is needed.
- Use `bg_list` to inventory all tracked terminals.
- Use `bg_kill` when a process is no longer needed or is stuck; termination continues even if the tool wait is aborted.
- Tell the user they can open `/ps` to inspect live output and kill terminals interactively.

Prefer meaningful titles and avoid starting duplicate servers or watchers. Full output is captured to spill files; tool and completion output shows a concise tail. Terminals are session-scoped and are stopped during shutdown or reload.

## Credit

By Davis (@davis7dotsh), from
https://github.com/davis7dotsh/my-pi-setup/blob/main/skills/background-terminals/SKILL.md