Tmux OrchestratorInstall

Overview

The Tmux Orchestrator node manages Claude AI agents running inside tmux terminal sessions. It enables orchestrating multiple AI agents by creating, messaging, monitoring, and terminating them within isolated tmux windows. This is useful for parallelizing AI workflows, managing long-running agent tasks, or coordinating complex multi-agent projects.

The Terminate Agent operation cleanly shuts down a specific agent by killing its tmux window while capturing the full conversation log from that window before termination. This ensures you preserve the agent’s output history for auditing or further processing.

Practical examples:

• Ending an AI agent session after task completion while saving its chat transcript.
• Cleaning up resources by closing idle or obsolete agent windows.
• Archiving agent conversations for review or debugging.

Properties

Output

The node outputs a JSON object with the following structure:

• success: Boolean indicating if the termination succeeded.
• terminatedWindow: The identifier of the tmux window that was terminated.
• conversationLog: A string containing the entire captured output (chat log) from the terminated window.
• timestamp: ISO 8601 timestamp when the termination occurred.

This output provides both confirmation of the termination and the full conversation history from the agent’s tmux window.

Dependencies

• Requires a system with tmux installed and accessible via command line.
• Uses Node.js child process execution to run tmux commands.
• Optionally integrates with external scripts or project base paths if configured in credentials.
• No direct external API dependencies; all orchestration happens locally on the tmux environment.

Troubleshooting

• Common issues:

  • If the specified targetWindow does not exist or is incorrect, the node will fail with an error indicating failure to capture output or kill the window.
  • Lack of permissions or missing tmux installation can cause command execution failures.
  • Concurrent tmux sessions or windows with similar names may cause ambiguity.

• Error messages and resolutions:

  • "Failed to terminate agent: <error message>": Indicates a problem executing tmux commands. Verify the targetWindow format and existence, ensure tmux is installed and accessible, and check user permissions.
  • "no server running" (in other operations): Means no tmux server is active; start a tmux session first.

• To resolve errors:

  • Confirm the targetWindow value matches an active tmux session and window.
  • Ensure the n8n runtime environment has access to tmux CLI.
  • Check for typos or formatting errors in the targetWindow input.

Links and References

• tmux Manual — Official documentation for tmux commands.
• Node.js child_process.execSync — Used for synchronous command execution.
• n8n Custom Node Development — Guide on building custom nodes in n8n.