Tmux Orchestrator

Orchestrate Claude AI agents through tmux sessions
Join our community

Actions7

Overview

The "Tmux Orchestrator" node manages Claude AI agents running inside tmux sessions and windows. It enables orchestrating multiple AI agents by creating, messaging, suggesting subagents, capturing output, checking status, listing sessions, and terminating agents within tmux terminal multiplexers.

The Suggest Subagent operation specifically allows the user to recommend deploying specialized subagents to improve parallel execution of tasks. This is useful in scenarios where a main agent needs to delegate subtasks to focused subagents (e.g., developers, project managers) for efficiency and scalability.

Practical examples:

  • A Project Manager agent suggests subagents specialized in development or testing to handle different features concurrently.
  • A Developer agent recommends subagents for debugging or code review to speed up implementation.
  • General agents can suggest subagents based on optional context like "handling multiple features" to optimize workload distribution.

Properties

Name Meaning
Target Window The tmux target window in session:window format where the suggestion will be sent (e.g., my-project:0). Required.
Agent Type The type of agent to suggest subagents to. Options:
- Project Manager
- Developer/Engineer
- General
Context Optional additional context string to provide more details about the suggestion (e.g., "handling multiple features").

Output

The JSON output from the Suggest Subagent operation includes:

  • success: Boolean indicating if the suggestion was successfully sent.
  • targetWindow: The tmux window identifier where the suggestion was made.
  • agentType: The type of agent targeted for subagent suggestions.
  • context: The optional context provided for the suggestion.
  • message: Confirmation message indicating the suggestion was sent.
  • timestamp: ISO timestamp of when the suggestion was made.

No binary data is output by this operation.

Example output:

{
  "success": true,
  "targetWindow": "my-project:0",
  "agentType": "developer",
  "context": "handling multiple features",
  "message": "Subagent suggestion sent to my-project:0",
  "timestamp": "2024-06-01T12:34:56.789Z"
}

Dependencies

  • Requires access to a tmux environment where Claude AI agents run inside tmux sessions and windows.
  • Optionally uses an API key credential for the tmux orchestrator service, which may specify external script directories or project base paths.
  • Relies on the tmux command-line tool being installed and accessible on the host system.
  • Uses Node.js child process execution to run tmux commands.
  • No other external services are required for the Suggest Subagent operation itself.

Troubleshooting

  • Common issues:

    • Invalid or incorrectly formatted targetWindow parameter (should be session:window).
    • tmux server not running or inaccessible, causing command failures.
    • Lack of permissions to execute tmux commands or access sessions.
    • Network or credential misconfiguration if using external scripts or API keys.

  • Error messages:

    • "Failed to suggest subagent: <error message>" indicates an issue sending the suggestion, often due to tmux command failure or communication problems.

  • Resolutions:

    • Verify the tmux session and window exist and are correctly specified.
    • Ensure tmux is installed and the user has permission to control it.
    • Check that any configured external scripts directory or project path is valid.
    • Confirm API credentials are properly set up if used.

Links and References

  • tmux Manual — Official documentation for tmux terminal multiplexer.
  • n8n Documentation — For general guidance on creating and using custom nodes.
  • Claude AI (Anthropic) — While not directly linked here, this node orchestrates Claude AI agents inside tmux sessions.

Discussion