Tmux Agent MonitorInstall

Overview

The Tmux Agent Monitor node is designed to monitor and analyze the activity and health of tmux agents running in tmux sessions. It provides various operations such as listing active sessions, performing health checks on agents, collecting logs, detecting blockers (stuck or blocked agents), generating activity reports, and more. This node is useful for system administrators, DevOps engineers, or developers who manage multiple tmux sessions and want to automate monitoring, troubleshooting, and reporting of agent activities within those sessions.

Practical examples:

• Running a health check to verify that all tmux agents respond correctly and are operational.
• Collecting recent logs from specific tmux sessions to diagnose issues.
• Detecting if any agents are stuck or waiting for input, helping to identify bottlenecks.
• Generating an activity report summarizing commands executed and errors detected over a specified period.

Properties

Note: These properties apply specifically to the Health Check operation under the "Default" resource.

Output

The node outputs JSON data structured according to the selected operation. For the Health Check operation, the output includes:

• success: Boolean indicating if the operation succeeded.
• summary: An object summarizing total windows checked, how many were healthy, unhealthy, and had errors.
• details: An array of objects, each representing a window checked with fields:
  • session: Session name.
  • window: Window name.
  • windowIndex: Index of the window.
  • healthy: Boolean indicating if the window responded with an acknowledgment.
  • hasErrors: Boolean indicating if error keywords were found.
  • responded: Boolean indicating if the window responded at all.
  • lastActivity: A snippet of the last captured content from the window.
• timestamp: ISO string timestamp of when the check was performed.

The node does not output binary data.

Dependencies

• Requires access to a tmux orchestrator API or environment capable of interacting with tmux sessions.
• Optionally uses credentials that may specify external script directories or project base paths for extended functionality.
• The node depends on a utility module (TmuxBridge) to interact with tmux sessions, send messages, and capture window content.

Troubleshooting

• Common issues:

  • Failure to connect to tmux sessions due to incorrect or missing API credentials.
  • Timeouts if agents do not respond within the specified Response Timeout.
  • Errors parsing session or window data if tmux environment is misconfigured.

• Error messages:

  • "Health check failed: <message>" indicates problems during the health check process, often related to communication with tmux or agent responsiveness.
  • "Failed to list sessions: <message>" suggests inability to retrieve tmux session information.

• Resolutions:

  • Verify that the tmux orchestrator API credentials are correctly configured and accessible.
  • Increase the Response Timeout if agents are slow to respond.
  • Ensure tmux sessions and windows exist and are properly named.
  • Check network connectivity and permissions for accessing tmux sessions.

Links and References

• tmux official documentation
• n8n Documentation
• Node.js fs module (for file operations) (used internally for log saving in other operations)