Shell Commands Fail with Signal 1 (SIGHUP) in tmux Panes - Workaround Found

[kr37swarm]

Discussion: Shell Commands Fail with Signal 1 (SIGHUP) in tmux Panes

Repository: google-gemini/gemini-cli
Category: Bug Report / Workaround Documentation
Related Issues: #12878, #15384, #13396

---

Summary

When Gemini CLI is spawned inside tmux panes, shell commands fail with Signal: 1 (SIGHUP) and produce empty output. Built-in shell commands (echo) work, but external binaries (ls, grep, cargo, npm) are killed immediately.

Workaround identified: Setting enableInteractiveShell: false in settings.json resolves the issue completely.

---

Environment

• OS: Ubuntu Linux 6.17.0-8-generic
• Gemini CLI: 0.22.5
• tmux: 3.5a
• Runtime: bun 1.3.5
• Spawn method: gemini --yolo inside tmux pane

---

Steps to Reproduce

1. Start a tmux session: tmux new -s test
2. Inside the tmux pane, launch Gemini CLI: gemini --yolo
3. Ask Gemini to run a shell command: "Run ls -la"
4. Observe the output shows Signal: 1 with empty output

---

Observed Behavior

Commands that WORK:

echo hello world → Output: "hello world", Signal: 0
read_file → works
list_directory → works

Commands that FAIL:

ls -la → Output: (empty), Signal: 1
which ls → Output: (empty), Signal: 1
grep "pattern" file → Output: (empty), Signal: 1
cargo test → Output: (empty), Signal: 1
npm run build → Output: (empty), Signal: 1

---

Root Cause Analysis

Based on source code analysis and session forensics:

1. PTY Initialization Fails in tmux

When enableInteractiveShell: true (default behavior when the setting is present), Gemini CLI attempts to use node-pty for shell execution. In tmux panes:

• PTY initialization can fail (due to /dev/ptmx access or native module issues)
• CLI falls back to child_process.spawn with detached: true

2. Detached Process Group Gets Orphaned

On Linux, detached: true creates a new process group. In tmux:

• The detached process group becomes "orphaned"
• Per POSIX, orphaned process groups receive SIGHUP

3. Signal Handling Difference

• Bash: Ignores SIGHUP when running detached (SIG_IGN inherited)
• External binaries: Reset signal handler to default (SIG_DFL = terminate)
• Result: Bash builtins work, but any forked external binary is immediately killed by the pending SIGHUP

Evidence from session logs:

{
  "command": "echo hello world",
  "Exit Code": 0, "Signal": 0  // Works - bash builtin
}
{
  "command": "ls -la /home/ubuntu",
  "Exit Code": 0, "Signal": 1  // Killed by SIGHUP - external binary
}

---

Workaround (Verified Working)

Add to ~/.gemini/settings.json:

{
  "tools": {
    "shell": {
      "enableInteractiveShell": false
    }
  }
}

Result: ALL shell commands work correctly.

Test results after applying fix:

echo hello → "hello" (Signal: 0)
ls -la /home/ubuntu → Full directory listing (Signal: 0)
which ls → "/usr/bin/ls" (Signal: 0)
grep pattern file → Works (Signal: 0)

Trade-off

Interactive commands (vim, htop, git rebase -i) won't work. For agent automation and development tasks, this is acceptable.

---

Relationship to Existing Issues

Issue	Connection
#12878	Proposes making node-pty optional - this workaround effectively does that
#15384	Loop behavior when shell commands fail - same root cause
#13396	tmux server being killed - possibly related to process group handling

---

Suggested Improvements

1. Documentation: Document that tmux users should set enableInteractiveShell: false

2. Auto-detection: Detect $TMUX environment variable and automatically disable interactive shell:

   if (process.env.TMUX) {
     options.detached = false;
   }

3. Fallback behavior: When node-pty fails, don't use detached: true in the child_process fallback

4. Warning message: If shell commands fail with Signal 1, suggest the workaround to the user

---

Use Case

We're running multi-agent development swarms using ntm which spawns Claude, Codex, and Gemini agents in tmux panes. Gemini agents were entering infinite loops because shell commands kept failing, triggering loop protection, and bricking the agents.

The enableInteractiveShell: false workaround makes Gemini agents fully functional for development tasks in tmux environments.

---

Questions

1. Is this the expected behavior when node-pty fails?
2. Should the fallback code path avoid detached: true?
3. Would a PR adding tmux detection be welcome?

---

CC: @krasmussen37