Tmux Orchestrator

Orchestrate Claude AI agents through tmux sessions
Join our community

Actions7

Overview

The Tmux Orchestrator node enables orchestration of Claude AI agents running inside tmux sessions and windows. It allows users to manage these agents by deploying new ones, sending messages, suggesting subagents for parallel task execution, capturing output logs, checking status, listing active sessions, and terminating agents.

This node is beneficial in scenarios where multiple AI agents need to be managed concurrently within terminal multiplexers (tmux), such as automating software development workflows, coordinating AI-driven project management, or running parallel testing and code review tasks.

Practical examples:

  • Deploy a developer agent in a new tmux session to automate coding tasks.
  • Send messages to an existing agent to provide instructions or queries.
  • Suggest specialized subagents to improve parallel execution efficiency.
  • Capture recent output from an agent’s tmux window for logging or analysis.
  • Terminate an agent cleanly after task completion.

Properties

Name Meaning
Target Window The tmux target window in the format session:window (e.g., my-project:0) where the message or command will be sent. Required for operations like sending messages, suggesting subagents, capturing output, and terminating agents.
Message The text message to send to the agent in the specified target window. Used only in the "Send Message" operation.

Output

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

  • success: Boolean indicating if the message was sent successfully.
  • targetWindow: The tmux window identifier where the message was sent.
  • messageSent: The actual message string that was sent.
  • timestamp: ISO timestamp of when the message was sent.

Other operations produce outputs relevant to their function, such as session lists, captured output logs, or deployment confirmations.

The node does not output binary data.

Dependencies

  • Requires access to a system with tmux installed and accessible via command line.
  • Uses Node.js child process execution to run tmux commands.
  • Optionally uses credentials that may specify external script directories or project base paths for advanced configurations.
  • No direct external API dependencies beyond local tmux environment.

Troubleshooting

  • Common issues:

    • Failure to execute tmux commands if tmux is not installed or the tmux server is not running.
    • Incorrect targetWindow format causing command failures.
    • Permission issues when executing shell commands.
    • Delays or timeouts when deploying agents due to slow startup scripts.

  • Error messages and resolutions:

    • "Failed to send message: ...": Check that the target window exists and is correctly formatted; verify tmux server is running.
    • "Failed to deploy agent: ...": Ensure the session name is unique and the project path (if provided) is valid; confirm tmux is installed.
    • "Failed to capture output: ...": Verify the target window is active and accessible.
    • "Failed to list sessions: no server running": Start the tmux server before using the node.
    • General permission errors: Run n8n with sufficient privileges to execute tmux commands.

Links and References

  • tmux Manual — Official documentation for tmux commands and usage.
  • Node.js child_process.execSync — Documentation on synchronous command execution in Node.js.
  • Claude AI — Information about Claude AI agents (for context on the orchestrated agents).

Discussion