Tmux Orchestrator

Orchestrate Claude AI agents through tmux sessions
Join our community

Actions7

Overview

The "Tmux Orchestrator" node manages and interacts with tmux sessions to orchestrate Claude AI agents. It allows users to deploy new agents, send messages, suggest subagents for parallel task execution, capture output from agent windows, check the status of sessions, list active sessions, and terminate agents cleanly.

This node is beneficial in scenarios where multiple AI agents need to be managed concurrently within terminal multiplexers (tmux), enabling parallel workflows and efficient resource use. For example, a software development team could deploy different AI agents as developers, QA engineers, or project managers in separate tmux sessions, communicate with them, and monitor their activity all within n8n.

Practical examples:

  • Deploying a developer agent in a new tmux session to assist with coding tasks.
  • Sending instructions or queries to an existing agent window.
  • Listing all active tmux sessions filtered by name to monitor running agents.
  • Capturing recent output logs from an agent’s tmux window for review.
  • Terminating an agent session after task completion.

Properties

Name Meaning
Session Filter Optional string filter to narrow down session names when listing sessions or getting status.

(Note: The above property is relevant for the "List Sessions" and "Get Status" operations.)

Output

The node outputs JSON objects containing operation-specific results:

  • List Sessions operation returns:
    • success: Boolean indicating if the operation succeeded.
    • sessions: Array of session names matching the optional filter.
    • count: Number of sessions found.
    • timestamp: ISO timestamp of when the data was retrieved.

Other operations produce outputs relevant to their function, such as success flags, session/window identifiers, messages sent, captured output text, or error messages.

The node does not output binary data.

Dependencies

  • Requires tmux installed and accessible on the host system where n8n runs.
  • 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:

    • "no server running" error when listing sessions indicates tmux server is not active; start tmux manually or ensure it runs before using the node.
    • Permission issues executing tmux commands due to environment restrictions.
    • Invalid session or window names causing command failures.

  • Error Messages:

    • Errors like Failed to deploy agent: ... or Failed to send message: ... indicate underlying tmux command failures or invalid parameters.
    • To resolve, verify tmux installation, session/window names, and input parameters.
    • Ensure the target tmux session/window exists before sending messages or capturing output.
    • Use the "Session Filter" property carefully to avoid filtering out all sessions unintentionally.

Links and References

Discussion