# background-worker

> Background Worker - Dispatch edits/tasks to keep main context clean

- Author: Claude Assistant
- Repository: mfethe1/skills
- Version: 20260123221508
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/mfethe1/skills
- Web: https://mule.run/skillshub/@@mfethe1/skills~background-worker:20260123221508

---

---
name: background-worker
description: Background Worker - Dispatch edits/tasks to keep main context clean
triggers:
  - edit
  - fix
  - update
  - change
  - modify
  - refactor
  - implement
  - add
  - create
  - write
  - dispatch
  - background
---

# Background Worker Skill

## Description
Offload well-defined, isolated tasks to a background process to prevent context rot and keep the main session focused.

## When to Use
- **Routine Maintenance**: "Fix all lint errors", "Format code", "Update dependencies".
- **Long-Running Operations**: "Run full test suite", "Scrape documentation for X".
- **Isolated Tasks**: Tasks that don't require further user interaction once started.

## How to Use
Use the `run_shell_command` tool to dispatch tasks using the `dispatch.py` script.

### Syntax
```bash
python C:\Users\mfeth\.gemini\hooks\dispatch.py "Task Description" [--cwd /path/to/work] [--priority LEVEL]
```

### Examples
1.  **Fix Lint Errors**:
    ```bash
    python C:\Users\mfeth\.gemini\hooks\dispatch.py "Fix all lint errors in src/" --priority MEDIUM
    ```

2.  **Run Tests**:
    ```bash
    python C:\Users\mfeth\.gemini\hooks\dispatch.py "Run tests for auth module" --cwd ./backend --priority HIGH
    ```

## Resilient Architecture (v2026)
The system now features a self-healing background architecture:
1. **Automatic Startup**: The `SessionStart` hook uses `worker_starter.py` to initiate the background daemon using platform-specific detached processes.
2. **Lazy Worker Fallback**: If the daemon fails to start or is killed, the `PostToolUse` hook implements a "Lazy Worker" pattern, processing one queued task per tool call to ensure eventual completion.
3. **Multi-Instance Safety**: Uses SQLite WAL mode and advisory file locking to prevent race conditions between the daemon and lazy workers.

## Verification
You can check the status of background tasks by running:
```bash
python C:\Users\mfeth\.gemini\hooks\background_worker.py --status
```
If the status shows `STOPPED`, the **Lazy Worker** will still process your tasks sequentially.

## Best Practices
- **Be Specific**: The background worker runs in isolation. Provide clear, self-contained instructions.
- **Set Working Directory**: Always specify `--cwd` if the task is specific to a subdirectory.
- **Check Logs**: If a task fails, check `~/.gemini/logs/bg_worker.log` for details.