Tmux Agent MonitorInstall

Overview

The Tmux Agent Monitor node is designed to monitor and analyze activity within tmux sessions managed by an orchestrator. It provides various operations such as listing active sessions, performing health checks on agents, collecting logs, detecting blockers (stuck or problematic agents), generating activity reports, and more.

For the Collect Logs operation specifically, the node aggregates logs from tmux agent windows across specified sessions. It can collect a configurable number of lines per window and optionally save these logs to files in a specified directory.

Common scenarios where this node is beneficial:

• Debugging and auditing tmux-based agent workflows by collecting recent logs.
• Centralizing log data for multiple tmux sessions and windows.
• Archiving logs for later analysis or compliance purposes.
• Quickly gathering diagnostic information during incident investigations.

Practical example:

You have several tmux sessions running automated agents that perform tasks. You want to collect the last 100 lines of logs from each window across all sessions and save them to files for offline review. Using this node with the "Collect Logs" operation, you specify the number of lines per window, enable saving to files, and set the output directory. The node then fetches the logs and writes them to timestamped files.

Properties

Output

The node outputs a JSON object containing:

• success: Boolean indicating if the log collection succeeded.
• logsCollected: Number of logs collected (one per window).
• logs: An array of objects, each representing logs from a single tmux window, including:
  • session: The tmux session name.
  • window: The window name.
  • windowIndex: The index of the window within the session.
  • timestamp: ISO string timestamp when logs were collected.
  • content: The full captured log content (in the output summary, truncated to first 500 characters followed by ellipsis).
  • savedTo (optional): If saving to file is enabled, the full path to the saved log file.
• savedToFiles: Boolean indicating if logs were saved to files.
• outputDirectory: The directory path where files were saved (or null if not saved).
• timestamp: ISO string timestamp of the overall operation.

If saving to files is enabled, the node writes each window's logs to a separate .log file named using the pattern {session}_{window}_{timestamp}.log.

Dependencies

• Requires access to a tmux orchestrator API or environment capable of providing tmux session and window information and capturing window content.
• Optionally depends on filesystem access to write log files if "Save to File" is enabled.
• No explicit external API keys are required, but credentials for the tmux orchestrator API may be configured in n8n.
• Node uses internal utilities to interact with tmux sessions and windows.

Troubleshooting

Common Issues

• Empty or missing logs:
  Ensure the target sessions exist and contain windows with accessible content. Verify the tmux orchestrator API is reachable and properly authenticated.

• Permission errors when saving files:
  Confirm the output directory exists or can be created by the node process and that it has write permissions.

• Incorrect session names in "Target Sessions":
  Use exact session names separated by commas without extra spaces to avoid filtering out desired sessions.

Common Error Messages

• "Failed to collect logs: <error message>"
  Indicates failure during fetching or processing logs. Check connectivity to tmux orchestrator and validity of parameters.

• Filesystem errors related to directory creation or file writing may appear if the output directory is invalid or inaccessible.

Links and References

• tmux official documentation — For understanding tmux sessions and windows.
• n8n Custom Nodes Documentation — Guidance on creating and configuring custom nodes.
• Node.js fs module — Used internally for file operations when saving logs.