Prevents background bash tasks in Claude Code from respawning infinitely. Installs as a PreToolUse hook that tracks spawn attempts per command pattern within a sliding time window and blocks execution when the limit is exceeded.
Background bash tasks (run_in_background: true) can respawn indefinitely when commands hang, creating fork bombs that consume all system resources.
- Intercepts every
Bashtool call via the Claude Code hook system - Ignores foreground tasks — only monitors
run_in_background: true - Normalizes the command (collapsing numbers and temp paths) and hashes it to group similar invocations
- Tracks spawn timestamps in
/tmp/claude-bg-tasks/per pattern - If a pattern exceeds the respawn limit within the time window:
- Kills existing processes matching the command
- Logs the incident
- Blocks the new spawn (exit code 2)
# Requires jq
./install.shThis adds a PreToolUse hook to ~/.claude/settings.json.
Set environment variables before launching Claude Code:
| Variable | Default | Description |
|---|---|---|
BG_TASK_MAX_RESPAWNS |
5 |
Max spawn attempts per command pattern |
BG_TASK_WINDOW_SECONDS |
300 |
Sliding time window (seconds) |
BG_TASK_TRACK_DIR |
/tmp/claude-bg-tasks |
Directory for tracking files |
BG_TASK_LOG_FILE |
/tmp/claude-bg-task-limiter.log |
Incident log path |
Remove the bg-task-limiter.sh entry from hooks.PreToolUse in ~/.claude/settings.json.
See LICENSE.