Skip to content

Improve TMUX dependency error message for BashExecutor setup#22

Closed
malhotra5 wants to merge 1 commit intomainfrom
openhands/improve-tmux-error-message
Closed

Improve TMUX dependency error message for BashExecutor setup#22
malhotra5 wants to merge 1 commit intomainfrom
openhands/improve-tmux-error-message

Conversation

@malhotra5
Copy link
Collaborator

Summary

  • Implements a friendly, actionable error message when tmux is not installed or not found in PATH during BashExecutor initialization.
  • Prevents a noisy stack trace and clearly explains that tmux is required locally for the CLI to manage shell sessions.
  • Adds unit tests to ensure this behavior is covered and remains stable.

What is the change?

  • In openhands_cli/agent_chat.py, wrap BashExecutor initialization in a try/except block.
  • Detect libtmux.exc.TmuxCommandNotFound (and similar cases) and print a clear guidance message, including installation examples for macOS and popular Linux distros.
  • Return gracefully without proceeding to agent startup when tmux is missing.

Why is this change needed?

How is this tested?

  • Added tests/tests_agent_chat.py:
    • test_setup_agent_handles_missing_tmux: Mocks BashExecutor to raise TmuxCommandNotFound and asserts the friendly messages are printed and setup_agent returns (None, None, None).
    • test_setup_agent_handles_missing_tmux_by_name: Ensures we also catch cases where the exception type may not be importable but the name/message indicates tmux is missing.
  • All tests pass locally: 13 passed.

Related issues

Checklist

  • Code compiles and is formatted (ruff/black)
  • Lint passes (pre-commit)
  • Unit tests added and passing
  • Does not change public API

Additional notes

  • No documentation changes required. The behavior is self-explanatory in the CLI output.

@malhotra5 can click here to continue refining the PR

…n\n- Catch libtmux.exc.TmuxCommandNotFound and show actionable guidance\n- Explain tmux requirement and provide install commands for macOS/Linux distros\n- Return gracefully without stack trace so users understand next steps\n\nAlso adds unit tests for this behavior.\n\nCo-authored-by: openhands <openhands@all-hands.dev>
@malhotra5 malhotra5 closed this Sep 3, 2025
@malhotra5 malhotra5 deleted the openhands/improve-tmux-error-message branch September 5, 2025 06:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve TMUX dependency error message

2 participants