agent-monitor

name	agent-monitor
description	Agent work status monitoring and automatic activation system. Triggers when monitoring subagent runtime status, detecting prolonged unresponsive "stalled" states, and automatically activating them to resume operation. Suitable for long-running task monitoring, automated operations, agent health checks, and similar scenarios.

Permission Setup Review

python scripts/_init_dirs.py is an optional setup helper for the Agent Monitor - Agent Work Status Monitoring skill. It may apply broad filesystem permissions for compatibility. Show the target paths and permission mode, explain the risk, and prefer a narrower mode when shared write access is not needed.

Agent Monitor - Agent Work Status Monitoring

Overview

This skill provides subagent work status monitoring and automatic activation capabilities:

1. Status Monitoring - Real-time monitoring of agent runtime status
2. Stall Detection - Detecting "stalled" states where an agent has been unresponsive for over 5 minutes
3. Automatic Activation - Automatically sending activation messages to resume agent operation

Core Capabilities

1. Monitor Agent Status

Use the subagents tool to obtain a list of currently running agents:

# List recently running agents
subagents(action="list", recentMinutes=30)

2. Detect Stalled Status

Detection logic:

• Obtain the agent's last activity time
• Calculate the difference from the current time
• If over 5 minutes (300 seconds) with no activity → Determine as "stalled"

3. Automatically Activate Agents

Use the steer action of the subagents tool to send an activation message:

# Send an activation message to a specified agent
subagents(action="steer", target="<agent-id>", message="Continue working")

Workflow

┌─────────────────────┐
│  Get Agent List     │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ Check Each Agent's  │
│  Last Activity Time │
└──────────┬──────────┘
           ▼
      ┌────────┐
      │ >5min? ├──No──┐
      └────┬───┘      │
          Yes│         │
           ▼          │
┌─────────────────────┐│
│  Determine as       ││
│  Stalled Status     ││
└──────────┬──────────┘│
           ▼           │
┌─────────────────────┐│
│  Send Activation    ││
│  Message to Resume  ││
└─────────────────────┘│
           │           │
           └───────────┘
                 ▼
        ┌─────────────────┐
        │ Continue Monitoring│
        └─────────────────┘

Usage Examples

Example 1: Monitor All Agents

# 1. Get agent list
result = subagents(action="list", recentMinutes=30)

# 2. Check each agent's status
for agent in result.agents:
    idle_time = calculate_idle_time(agent.lastActivity)
    if idle_time > 300:  # Over 5 minutes
        # 3. Automatically activate
        subagents(action="steer", target=agent.id, message="Please continue executing the task")

Example 2: Monitor a Specific Agent

# Monitor an agent with a specified ID
agent_id = "builder-agent-001"
result = subagents(action="list", recentMinutes=10)

# Find the target agent
for agent in result.agents:
    if agent.id == agent_id:
        if is_stalled(agent, threshold=300):
            activate_agent(agent_id)

Script Tool

monitor_agents.py

Located at scripts/monitor_agents.py, provides complete monitoring functionality:

# Monitor and automatically activate stalled agents
python scripts/monitor_agents.py --threshold 300 --auto-activate

# Detect only, without automatic activation
python scripts/monitor_agents.py --threshold 300 --dry-run

# Monitor a specific agent
python scripts/monitor_agents.py --target agent-id-001

Parameter descriptions:

• --threshold: Stall determination threshold (seconds), default 300 (5 minutes)
• --auto-activate: Automatically activate stalled agents
• --dry-run: Detect only, do not execute activation
• --target: Specify a specific agent ID to monitor

Integration into Scheduled Tasks

The monitoring script can be integrated into cron scheduled tasks for continuous monitoring:

# Check every 2 minutes
*/2 * * * * python /path/to/monitor_agents.py --auto-activate

Notes

1. Threshold Setting: Adjust the stall determination threshold based on the task type; complex tasks may require longer thresholds
2. Activation Message: Activation messages sent should be concise and clear, prompting the agent to continue working
3. Avoid False Activation: Ensure the agent is genuinely stalled before activating to avoid interfering with normal thought processes
4. Logging: It is recommended to log each detection and activation operation for subsequent analysis