Improve TMUX dependency error message

[malhotra5]

The CLI installs the openhands/tool project from the agent-sdk dependency. This contains the tmux library. However, users still need tmux on their local machine to run the CLI.

The error throw is

Available options:
  1. Start Agent Chat - Interactive conversation with AI agent
  2. Show TUI Demo - Display TUI components
  3. Exit

Select an option (1-3): 1
Error setting up agent: 
Traceback (most recent call last):
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/openhands_cli/agent_chat.py", line 74, in setup_agent
    bash = BashExecutor(working_dir=cwd)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/openhands/tools/execute_bash/impl.py", line 14, in __init__
    self.session.initialize()
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/openhands/tools/execute_bash/bash_session.py", line 65, in initialize
    self.session = self.server.new_session(
                   ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/libtmux/server.py", line 517, in new_session
    if self.has_session(session_name):
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/libtmux/server.py", line 342, in has_session
    if exact and has_gte_version("2.1"):
                 ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/libtmux/common.py", line 354, in has_gte_version
    return get_version() >= LooseVersion(min_version)
           ^^^^^^^^^^^^^
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/libtmux/common.py", line 284, in get_version
    proc = tmux_cmd("-V")
           ^^^^^^^^^^^^^^
  File "/Users/rohitmalhotra/Documents/Openhands/OpenHands-CLI/.venv/lib/python3.12/site-packages/libtmux/common.py", line 225, in __init__
    raise exc.TmuxCommandNotFound
libtmux.exc.TmuxCommandNotFound

We should catch this exception and throw a user friendly warning which explains that tmux must be installed locally

[malhotra5]

@OpenHands please do this

[openhands-ai]

I'm on it! malhotra5 can track my progress at all-hands.dev

🔴 Solvability: HARD

This issue is extremely challenging to resolve due to the complete absence of any meaningful description, context, or technical details. The request consists only of a generic instruction without specifying what needs to be done, making it impossible to understand the problem or determine appropriate solutions.

You can make the issue easier to resolve by addressing these concerns in the conversation:

• Provide a clear, detailed description of what specific task or problem needs to be addressed
• Include relevant code snippets, error messages, or examples that demonstrate the issue
• Specify the expected behavior and current problematic behavior to clarify what needs to be fixed

[openhands-ai]

Final summary for issue #14: Improve TMUX dependency error message

What I changed

• Implemented friendly TMUX error handling in openhands_cli/agent_chat.py:
  • Wrapped BashExecutor initialization in try/except.
  • Detected libtmux.exc.TmuxCommandNotFound (and similar cases by name/message).
  • Printed actionable guidance explaining that tmux must be installed locally and included install examples for macOS and common Linux distros.
  • Returned gracefully to avoid a noisy stack trace when tmux is missing.
• Added tests in tests/test_agent_chat.py to verify:
  • setup_agent prints the friendly message and returns (None, None, None) when tmux is missing.
  • Defensive handling when only the exception name/message indicates tmux is missing.

Verification

• make test: 13 passed.
• make lint: Ran pre-commit hooks; code formatted by ruff; all checks passed after formatting.

Git/PR

• Branch: openhands/improve-tmux-error-message
• Commit: feat(cli): friendly error when tmux is missing in BashExecutor setup (includes tests)
• PR: Improve TMUX dependency error message for BashExecutor setup #22 (Fixes Improve TMUX dependency error message #14)

Checklist

• Clear, user-friendly error message for missing tmux.
• Added appropriate unit tests.
• All tests pass locally.
• Linting/pre-commit hooks pass.
• Concise changes: only openhands_cli/agent_chat.py and tests/test_agent_chat.py were modified/added.
• PR opened targeting main, with description that closes the issue.

If you’d like different wording for the message or to include Windows-specific guidance, I can adjust quickly.

_{View full conversation}

[malhotra5]

@OpenHands this is not an issue we should solve in this repo

please use the $GITHUB_TOKEN to open an issue in the agent-sdk repo

the requirements are roughly

1. if tmux isn't installed use the local terminal (or sub equivalent subprocess)
2. if we do default to the local terminal, make sure to throw a warning message to the user with instructions to install tmux locally

make sure this issue is concise yet descriptive. feel free to include the error log from this issue. DO NOT MAKE ANY CHANGES OR OPEN ANY PRs. Simply open the issue for the agent-sdk repo

[openhands-ai]

I'm on it! malhotra5 can track my progress at all-hands.dev

🟡 Solvability: MEDIUM

This issue involves creating a new issue in a different repository with specific requirements for tmux terminal handling, which follows standard development patterns but requires coordination across multiple components. The request is clearly structured with well-defined requirements, though it lacks some technical implementation details that could aid resolution.

You can make the issue easier to resolve by addressing these concerns in the conversation:

• Include specific error logs or examples that demonstrate the current tmux-related problems to provide concrete context for the new issue
• Add details about the current environment setup and how the terminal handling currently behaves to help developers understand the scope
• Specify any particular tmux version requirements or compatibility considerations that should be addressed

Positive feedback:

• The request follows standard development patterns with clear, structured requirements that are easy to understand
• External tools and technical components are clearly identified, making the scope well-defined
• The task is straightforward with simple, actionable language that reduces ambiguity about what needs to be accomplished

[openhands-ai]

Summary

I successfully created issue #87 in the All-Hands-AI/agent-sdk repository as requested, without making any changes to the OpenHands-CLI codebase.

Issue Created: OpenHands/software-agent-sdk#87
Title: "BashExecutor should fallback to local terminal when tmux is not available"

The issue includes:

• Complete problem description explaining the tmux dependency issue
• Full error traceback from the original OpenHands-CLI issue
• Your specified requirements:
  1. Fallback to local terminal when tmux isn't installed
  2. Display user-friendly warning with tmux installation instructions
• Technical implementation details for the agent-sdk team
• Reference to the original OpenHands-CLI issue for context

The issue is now open and ready for the agent-sdk team to implement the proper tmux fallback functionality with appropriate user messaging, addressing the root cause in the correct repository.

_{View full conversation}

[malhotra5]

This is an upstream issue tracking it in agent-sdk