Tmux Orchestrator

Orchestrate Claude AI agents through tmux sessions
Join our community

Actions7

Overview

The "Tmux Orchestrator" node enables orchestration of Claude AI agents within tmux terminal multiplexer sessions. It is designed to manage multiple AI agents running in parallel tmux windows, each potentially assigned a specific role such as Developer, Project Manager, QA Engineer, etc. This node facilitates deploying new agents, sending messages to them, suggesting subagents for parallel task execution, capturing their output, checking their status, listing active sessions, and terminating agents cleanly.

Common scenarios include:

  • Automating the deployment of AI agents tailored to different project roles.
  • Managing conversations with AI agents through tmux sessions.
  • Parallelizing tasks by suggesting specialized subagents.
  • Monitoring agent activity and retrieving logs or outputs.
  • Cleanly shutting down AI agents when no longer needed.

Practical example: A software team could deploy a Developer agent and a QA Engineer agent in separate tmux sessions, send them initial instructions, monitor their progress, and capture their outputs for review — all orchestrated programmatically via this node.

Properties

Name Meaning
Session Name Name of the tmux session where the agent will run (required).
Project Path Filesystem path to the project directory; sets the working directory for the tmux session.
Agent Role Role assigned to the agent, influencing its briefing and behavior. Options: Developer, Project Manager, QA Engineer, DevOps, Code Reviewer, Documentation Writer.
Initial Briefing Initial instructions or context provided to the agent after deployment (multi-line string).

Output

The node outputs JSON objects containing the results of the requested operation. For the "Deploy Agent" operation, the output includes:

  • success (boolean): Indicates if the deployment succeeded.
  • sessionName (string): The tmux session name used.
  • window (string): The tmux window identifier (format: session:window).
  • role (string): The assigned agent role.
  • projectPath (string): The project directory path used.
  • message (string): Confirmation message about deployment success.

Other operations produce outputs relevant to their function, such as message send confirmations, captured output text, session lists, or termination logs.

This node does not output binary data.

Dependencies

  • Requires a system environment with tmux installed and accessible via command line.
  • Uses Node.js child process execution (execSync) to run tmux commands.
  • Optionally uses credentials that may specify external script directories or project base paths.
  • No direct external API calls are made; interaction is local to the tmux environment.

Troubleshooting

Common Issues:

  • Tmux Not Installed or Running: Errors like "no server running" indicate tmux is not active or installed. Ensure tmux is installed and a server is running.
  • Permission Denied: Insufficient permissions to execute tmux commands or access project directories can cause failures.
  • Session Name Conflicts: Attempting to create a session with an existing name will fail.
  • Invalid Target Window Format: The target window parameter must be in the format session:window (e.g., my-project:0).

Error Messages and Resolutions:

  • Failed to deploy agent: ... — Check tmux installation, session name uniqueness, and project path validity.
  • Failed to send message: ... — Verify the target window exists and is correctly formatted.
  • Failed to capture output: ... — Confirm the target window is active and accessible.
  • Failed to list sessions: no server running — Start the tmux server before using the node.
  • Failed to terminate agent: ... — Ensure the target window exists and you have permission to kill it.

Links and References

Discussion