Tmux Project ManagerInstall

Overview

The Tmux Project Manager node facilitates managing software development projects within tmux sessions by coordinating project management tasks and team collaboration through automated messaging and session control. It is designed to help teams organize work, assign tasks, track progress, validate quality, add team members, and conduct daily standups—all within tmux terminal multiplexing environments.

This node is beneficial in scenarios where development teams use tmux sessions to simulate or orchestrate multiple agents (e.g., developers, QA engineers, reviewers) working concurrently on a project. It automates communication with these agents via scripted messages, enabling streamlined project coordination without leaving the terminal environment.

Practical examples:

• Automatically creating a new project tmux session with predefined windows for different roles.
• Assigning specific tasks to team members represented as tmux windows.
• Requesting status updates from all team members and aggregating their responses.
• Running quality validation checks such as code review or security audits by sending checklists to the project manager window.
• Adding new team members dynamically by opening new tmux windows and briefing them.
• Conducting daily standup meetings by collecting updates from each team member’s tmux window.

Properties

Output

The node outputs JSON objects containing the results of the selected operation. Common fields include:

• success: Boolean indicating if the operation succeeded.
• projectSession: The tmux session name used.
• Operation-specific data, e.g.:
  • For Validate Quality:
    • validationType: The chosen validation category.
    • validationRequested: Confirmation that the validation request was sent.
    • checklist: The list of quality criteria sent to the project manager.
    • pmResponse: The captured textual response from the project manager window summarizing the quality check.
    • timestamp: ISO string of when the operation completed.

If the node encounters errors and "Continue On Fail" is enabled, it returns an error object with an error message field.

The node does not output binary data.

Dependencies

• Requires access to a tmux environment where sessions and windows can be created and controlled.
• Uses an internal utility (TmuxBridge) to interact with tmux sessions, send messages, and capture window content.
• Optionally uses credentials that may specify external script directories or base paths for projects.
• Relies on the presence of a command-line tool or agent named "claude" running inside tmux windows to process messages and respond.

Troubleshooting

• Common issues:

  • Specified tmux session does not exist or is inaccessible.
  • The "claude" agent is not running or not responding in the tmux windows.
  • Insufficient permissions to create or control tmux sessions/windows.
  • Delays in receiving responses due to asynchronous message processing.

• Error messages and resolutions:

  • "Session <name> not found": Verify the tmux session name is correct and active.
  • "Failed to validate quality: <message>": Check that the tmux session is responsive and the "claude" agent is operational.
  • "Failed to assign task: <message>": Ensure target agent window exists and is ready to receive commands.
  • General failures often relate to tmux environment setup or missing dependencies; confirm tmux is installed and accessible by n8n.

Links and References

• tmux official documentation
• n8n Custom Node Development Guide
• Concepts of terminal multiplexing and automation with tmux sessions

This summary focuses on the Validate Quality operation within the Default resource, describing how the node requests quality checks from the project manager agent inside a tmux session and captures the resulting report.