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 enables 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), such as automating software development workflows, coordinating AI-driven project management, or running parallel testing and code review tasks.

Practical examples:

  • Deploying a developer agent in a new tmux session to automate coding tasks.
  • Sending instructions or queries to an existing agent window.
  • Suggesting specialized subagents to improve efficiency by parallelizing work.
  • Capturing recent logs or outputs from an agent's tmux window for monitoring.
  • Listing all active tmux sessions filtered by name patterns.
  • Checking health and activity status of tmux sessions and their windows.
  • Terminating an agent session while preserving its conversation log.

Properties

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

Output

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

  • success: Boolean indicating if the operation succeeded.
  • timestamp: ISO string timestamp of when the operation was performed.

Depending on the operation, additional fields are present:

  • Get Status:

    • sessions: Array of session objects, each with:
      • sessionName: Name of the tmux session.
      • attached: Boolean indicating if the session is attached.
      • windows: Array of windows with index, name, and active status.

  • List Sessions:

    • sessions: Array of session names matching the filter.
    • count: Number of sessions found.

  • Deploy Agent:

    • sessionName: Name of the created session.
    • window: Window identifier (e.g., "session:0").
    • role: Role assigned to the agent.
    • projectPath: Path used for the session (if any).
    • message: Confirmation message.

  • Send Message, Suggest Subagent:

    • targetWindow: Target tmux window.
    • messageSent or message: Confirmation message.
    • agentType and context for subagent suggestions.

  • Capture Output:

    • output: Captured text output from the tmux window.
    • linesCaptures: Number of lines captured.

  • Terminate Agent:

    • terminatedWindow: Identifier of the terminated window.
    • conversationLog: Text log captured before termination.

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.
  • No direct external API dependencies beyond local tmux environment.

Troubleshooting

  • Common Issues:

    • "Failed to get status: ..." or similar errors often indicate tmux is not running or accessible.
    • Permission issues running tmux commands.
    • Incorrect session or window names causing command failures.
    • Delays in agent startup might require adjusting wait times.

  • Error Messages and Resolutions:

    • "Failed to deploy agent: ..." — Check that tmux is installed and the session name is unique.
    • "Failed to send message: ..." — Verify the target window exists and is correctly formatted (session:window).
    • "Failed to capture output: ..." — Ensure the target window is active and has sufficient history.
    • "Failed to list sessions: no server running" — Indicates tmux server is not running; start tmux manually or ensure it auto-starts.
    • Use the node’s "Continue On Fail" option to handle errors gracefully during batch operations.

Links and References

Discussion