Tmux Agent MonitorInstall

Overview

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

For example, you can use the Activity Report operation to generate a summary of activity levels, commands executed, and errors detected across specified tmux sessions over a selected time period. This helps in understanding session usage patterns and identifying potential issues.

Properties

Output

The output JSON structure for the Activity Report operation includes:

• success: Boolean indicating if the report generation was successful.
• reportPeriod: The selected time period for the report (e.g., "hour", "day").
• summary: An object summarizing:
  • totalSessions: Number of sessions included in the report.
  • totalWindows: Total number of windows across all sessions.
  • activeWindows: Count of windows currently active.
  • totalCommands: Total number of commands executed across all windows.
  • totalErrors: Total number of error occurrences detected.
• activityData: Array of session objects, each containing:
  • session: Session name.
  • attached: Boolean indicating if the session is attached.
  • windows: Array of window objects with:
    • name: Window name.
    • index: Window index.
    • active: Boolean indicating if the window is active.
    • activityLevel: Number of non-empty lines in the window content.
    • commandsExecuted: Number of command lines starting with $ or >.
    • errorsDetected: Number of lines containing error keywords.
    • lastActivity: Last few lines of window content showing recent activity.
• timestamp: ISO timestamp when the report was generated.

This output allows detailed inspection of tmux session activities and error occurrences.

Dependencies

• Requires access to a tmux orchestrator API or environment where tmux sessions are running.
• Optionally uses credentials that may specify external script directories or project base paths.
• Node depends on an internal utility (TmuxBridge) to interact with tmux sessions, capture window content, and send messages.
• If saving logs (in other operations), requires filesystem access permissions.

Troubleshooting

• Common Issues:

  • Empty or incorrect Target Sessions input may result in no data or incomplete reports.
  • Insufficient permissions or missing tmux environment can cause failures in fetching session data.
  • Network or API credential misconfiguration might prevent communication with the tmux orchestrator.

• Error Messages:

  • "Failed to generate activity report: <error message>": Indicates failure during report creation; verify tmux availability and credentials.
  • "Health check failed: <error message>": Occurs if agents do not respond; check agent status and response timeout settings.
  • "Failed to collect logs: <error message>": Happens if log retrieval or file writing fails; ensure directory permissions and disk space.

• Resolutions:

  • Double-check session names and ensure they exist.
  • Verify API credentials and connectivity.
  • Adjust timeouts and thresholds according to environment responsiveness.
  • Ensure the node has necessary filesystem permissions if saving files.

Links and References

• tmux Official Documentation
• n8n Custom Node Development Guide
• Node.js File System Module (relevant for log saving)

This summary focuses on the Activity Report operation of the Tmux Agent Monitor node, describing its inputs, outputs, dependencies, and common troubleshooting tips based on static code analysis.