# Check On Task

> Check status of background tasks and coding agents — discover running processes, detect stalls, analyze progress, and generate clear reports.

- Skill: `colindmurray/check-on-task` (Agent Skill)
- Install (CLI): `npx skillmds@latest add colindmurray/check-on-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/colindmurray/check-on-task/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: colindmurray (https://skillmd.com/u/colindmurray)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/colindmurray/check-on-task

---


# Check on Task

Check the status of ANY background task launched by `execute_long_running_task`.

## Usage

```bash
# Check a specific task
~/.openclaw/skills/long-running-task/bin/check_task --task-id <TASK_ID>

# Check all tasks for a session
~/.openclaw/skills/long-running-task/bin/check_task --session-id <SESSION_ID>

# Check all active tasks
~/.openclaw/skills/long-running-task/bin/check_task --all

# JSON output (for programmatic use — includes system memory info)
# Output shape: {"tasks": [{...}, ...], "system": {...}}  — task array is wrapped under "tasks"
~/.openclaw/skills/long-running-task/bin/check_task --all --json

# Custom stall threshold (default 600s = 10 min)
~/.openclaw/skills/long-running-task/bin/check_task --task-id <ID> --stall-threshold 300
```

## Status Meanings

| Status | Meaning |
|--------|---------|
| **running** | PID alive, output flowing normally |
| **stalled** | PID alive but no output for >stall-threshold seconds |
| **completed** | Process exited with code 0 |
| **failed** | Process exited with non-zero code |
| **dead** | PID not found (auto-moved to failed) |

## Health Indicators

| Health | Meaning |
|--------|---------|
| **ok** | Everything normal |
| **stalled** | Output file not written to recently |
| **hang-detected** | (Coding agents) Result event received but PID still alive — safe to kill |
| **error** | Process failed or PID dead |

## Monitor Watchdog

Each background task launched with `--mode heartbeat` gets a **monitor watchdog** (`monitorPid`):
- Runs as a sibling process that survives if the task dies (OOM, SIGKILL)
- Checks PID liveness every 120 seconds
- If the task dies unexpectedly, the monitor:
  - Moves the manifest to `failed/` with `monitorDetected: true`
  - Sends a notification immediately
  - Fires a system event to wake the AI for retry decisions

### Interpreting Monitor Fields

| Field | Meaning |
|-------|---------|
| `monitorPid` | PID of the watchdog process |
| `monitorPid (alive)` | Monitor is actively watching the task |
| `monitorPid (dead)` | Monitor died — task has no fast-path death detection |
| `monitorDetected: true` | Task death was caught by monitor (fast-path, <2 min) |
| No `monitorDetected` | Task death was caught by cleanup_tasks (slow-path, up to 30 min) |

If `monitorDetected: true`, the user has already been notified — focus on interpretation and retry decisions, not re-notification.

## For Coding Agents

When the task type is `coding-agent`, you get deeper analysis:

- **Tool counts**: how many Read/Edit/Bash tools the agent has used
- **Error count**: error events in the NDJSON stream
- **Phase estimation**: exploring (read-heavy), implementing (edit-heavy), testing (bash-heavy)
- **Git progress**: commits since task start, unstaged changes
- **Hang detection**: Claude stream-json bug where process stays alive after `result` event
- **System memory**: current memory usage (useful for OOM risk assessment)

## Caution on Killing

Only kill a process if it is clearly stuck (completely silent output for extended period, error loops, or hang detected with result event + PID alive). Coding agents often have long pauses between tool calls — this is normal.