Tmux OrchestratorInstall

Overview

The "Tmux Orchestrator" node enables orchestration of Claude AI agents running inside tmux terminal multiplexing sessions. It allows users to deploy new agents, send messages to them, suggest subagents for parallel task execution, capture recent output from agent windows, check agent status, list active sessions, and terminate agents cleanly.

This node is beneficial in scenarios where multiple AI agents need to be managed concurrently within isolated tmux sessions, such as automating software development workflows, project management, QA testing, or DevOps tasks. For example, a user can deploy a developer agent in a tmux session, send it instructions, capture its output logs, and later terminate the session when done.

Properties

Output

The node outputs JSON objects containing the results of the selected operation. For the Capture Output operation, the output includes:

• success: Boolean indicating if the operation succeeded.
• targetWindow: The tmux window identifier from which output was captured.
• linesCaptures: Number of lines requested to capture.
• output: The captured text output from the tmux pane.
• timestamp: ISO timestamp of when the capture occurred.

Other operations return similarly structured JSON with success flags, relevant identifiers, messages, and timestamps.

The node does not output binary data.

Dependencies

• Requires access to a system with tmux installed and accessible via command line.
• Optionally uses an API key credential for external scripts configuration (if provided).
• Uses Node.js child process execution to run tmux commands.
• No additional external services are required beyond tmux and local environment setup.

Troubleshooting

• Common Issues:

  • Failure to execute tmux commands if tmux is not installed or the tmux server is not running.
  • Incorrect targetWindow format or non-existent tmux session/window causing errors.
  • Permission issues executing shell commands.

• Error Messages:

  • "Failed to capture output: ..." indicates inability to run the tmux capture-pane command; verify tmux session/window exists.
  • "Failed to deploy agent: ..." suggests problems creating a new tmux session or sending initial commands; check session name uniqueness and directory paths.
  • "Failed to send message: ..." means sending keys to tmux window failed; confirm target window is correct and active.
  • "Failed to terminate agent: ..." occurs if killing the tmux window fails; ensure the window exists and you have permissions.

• Resolutions:

  • Ensure tmux is installed and running (tmux ls should list sessions).
  • Validate all input parameters, especially targetWindow.
  • Run n8n with sufficient permissions to execute shell commands.
  • Check that any configured external scripts directories exist and are accessible if used.

Links and References

• tmux Manual — Official documentation for tmux commands.
• Node.js child_process.execSync — Used for synchronous command execution.
• n8n Documentation — General information on creating and using custom nodes.