tmux send-keys hangs indefinitely, blocks listener loop

[MichaelC001]

Related to #5 (Large text not sending).

I've been investigating a more severe version of this problem. tmux send-keys -l can hang indefinitely (not just slow — the process never exits), which blocks the entire listener getUpdates loop and prevents receiving any new Telegram messages.

What happens

1. tmux send-keys -t <target> -l "<text>" is called to paste text into Claude Code
2. The tmux client enters proc_loop() waiting for the server to respond
3. If Claude Code is not reading stdin fast enough, the PTY kernel buffer fills up (~4096 bytes on macOS)
4. The tmux server's bufferevent_write() gets EAGAIN, stalling the event loop
5. The send-keys client process never exits — proc_loop() has no timeout mechanism
6. Our Go code calls cmd.Run() which blocks forever waiting for the process

I found 5 stuck tmux send-keys processes on my machine, one running for 8+ hours.

Ghost messages

After killing the stuck processes, data already written to the tmux server's buffer remains in the PTY kernel buffer. When Claude Code eventually reads stdin, it processes this stale data as new prompts — executing commands the user never sent. This is a security concern since Claude may execute dangerous operations from ghost input.

What I've tried

• Added timeout via exec.CommandContext — prevents listener hang, but doesn't prevent ghost messages
• Sending Escape + Ctrl-U before each send-keys — clears TUI input, but can't flush kernel PTY buffer
• The PTY kernel buffer on macOS is not user-configurable

tmux internals

• proc_loop() in proc.c has no timeout
• Related tmux issues: send-keys commands are sporadically dropped tmux/tmux#1185, tmux send-keys very slow on FreeBSD tmux/tmux#1812, tmux frozen, ls or attach freezing as well tmux/tmux#2324

Environment

• macOS (Darwin), tmux 3.5a, Go
• Happens most often with photo messages (longer text + 2s delay before send-keys)

Any ideas on how to solve the ghost message problem? I've been thinking about this for a while and haven't found a clean solution.

[kidandcat]

Investigation: tmux send-keys Hang Analysis & Alternatives

Root Cause Confirmed

The issue is exactly as described. In the CCC codebase there are 12 direct send-keys calls across tmux.go and commands.go, and none of them have timeout protection:

File	Lines	Context	Error handled?
tmux.go	167	Window creation (ccc run)	No
tmux.go	268	Text input from Telegram (-l literal)	Yes
tmux.go	277, 279	Enter keys (C-m) after text	No
commands.go	848, 851	Option selection (Down + Enter)	No
commands.go	857	Submit answers (Enter)	No
commands.go	1453	Auth init	No
commands.go	1506, 1508, 1516, 1518, 1523	OAuth flow	No

The critical path is sendToTmuxWithDelay() at tmux.go:266-282:

func sendToTmuxWithDelay(target string, text string, delay time.Duration) error {
    cmd := exec.Command(tmuxPath, "send-keys", "-t", target, "-l", text) // ← CAN HANG
    if err := cmd.Run(); err != nil {
        return err
    }
    time.Sleep(100 * time.Millisecond)
    exec.Command(tmuxPath, "send-keys", "-t", target, "C-m").Run() // ← CAN HANG
    time.Sleep(50 * time.Millisecond)
    exec.Command(tmuxPath, "send-keys", "-t", target, "C-m").Run() // ← CAN HANG
    return nil
}

Why Claude Code Requires TTY

Claude Code uses Ink (React for terminals). Ink checks process.stdin.isTTY and enables raw mode. When stdin is not a TTY, Claude Code either crashes with "Raw mode is not supported" or falls back to --print mode (non-interactive, no permissions, no streaming). Any solution must preserve isatty(stdin) == true.

---

Alternative Analysis

1. FIFO (Named Pipes) for Input — ❌ Dead End

Concept: claude < /path/to/fifo, Go code writes to the FIFO.

Fatal flaw: A FIFO is not a TTY. isatty() returns false, Ink crashes. Additionally, Ink's ink-text-input treats programmatic \r/\n as newlines rather than submit actions (claude-code#15553).

FIFO writes also block when the reader's buffer is full (same class of problem we're trying to solve).

Verdict: Not viable.

2. Own PTY via creack/pty — ✅ Best Long-Term

Concept: Create a PTY pair in Go, run Claude Code on the slave side, write/read via master fd.

import "github.com/creack/pty"
cmd := exec.Command(claudePath, args...)
ptmx, err := pty.Start(cmd)
ptmx.Write([]byte("prompt text\r"))  // atomic write, no tmux intermediary

Criterion	Assessment
TTY preserved?	✅ Slave PTY passes isatty()
Solves blocking?	✅ Direct PTY write, no tmux proc_loop()
Solves ghost messages?	✅ Atomic write of text+Enter
Complexity	High

Challenges:

• Output parsing: Raw PTY output includes all ANSI escape sequences from Ink's TUI. Would need a virtual terminal emulator library (go-ansiterm, go-vte) to extract meaningful text — significantly more complex than tmux capture-pane.
• Session persistence lost: If the Go process dies, Claude Code dies. Tmux provides detach/reattach.
• User visibility lost: No way to "attach" and watch Claude Code unless we build that.
• Window size management: Must handle pty.Setsize() manually.

Verdict: Technically the strongest solution. Eliminates tmux from the critical path entirely. But the output parsing and loss of session visibility make this a significant rewrite. Best as a future investment.

3. Fork of tmux with proc_loop() timeout — ❌ Impractical

Concept: Patch tmux's proc.c to add a timeout to proc_loop().

Issues:

• Maintaining a tmux fork is a significant burden
• The root cause is in the kernel PTY buffer, not tmux's event loop per se
• A timeout in proc_loop() would make send-keys exit, but the data already written to the server buffer creates the same ghost message problem
• tmux upstream unlikely to merge (related issues #1185, #1812, #2324 remain open for years)

Verdict: High maintenance, doesn't solve ghost messages, impractical.

4. Hybrid: tmux for display, FIFO for input — ❌ Architecturally awkward

Concept: FIFO → bridge process → PTY master fd, while tmux handles display.

Problem: Tmux owns the PTY. You cannot write to tmux's PTY master from outside tmux. The only ways to inject input into a tmux pane are through tmux's own commands (send-keys, paste-buffer, pipe-pane, control mode) — which brings us back to the same problem. If you want to own the PTY yourself, you're essentially building option 2 with extra steps.

Verdict: Redundant with the creack/pty approach.

5. tmux paste-buffer -p (Bracketed Paste) — ✅ Best Near-Term

Concept: Instead of send-keys -l, use tmux's buffer mechanism with bracketed paste:

func sendToTmuxViaPaste(target string, text string) error {
    bufName := "ccc-input"
    // Load text into a named tmux buffer
    if err := exec.Command(tmuxPath, "set-buffer", "-b", bufName, text).Run(); err != nil {
        return err
    }
    // Paste with bracketed paste mode (-p)
    if err := exec.Command(tmuxPath, "paste-buffer", "-b", bufName, "-p", "-t", target).Run(); err != nil {
        return err
    }
    // Dismiss autocomplete popup + submit
    time.Sleep(100 * time.Millisecond)
    exec.Command(tmuxPath, "send-keys", "-t", target, "Escape").Run()
    time.Sleep(50 * time.Millisecond)
    exec.Command(tmuxPath, "send-keys", "-t", target, "Enter").Run()
    time.Sleep(50 * time.Millisecond)
    exec.Command(tmuxPath, "send-keys", "-t", target, "Enter").Run()
    return nil
}

Criterion	Assessment
TTY preserved?	✅ Claude Code stays in tmux PTY
Solves blocking?	⚠️ Partially — paste is still a PTY write, but through a different code path
Solves ghost messages?	✅ Bracketed paste is treated as atomic input by Ink
Complexity	Low — minimal change to tmux.go

Why this works: With paste-buffer -p, tmux wraps the text in bracketed paste escape sequences (ESC[200~...ESC[201~). Ink's TUI recognizes this and treats the entire content as a single paste operation, not individual keystrokes. The community has confirmed this pattern works for Claude Code (claude-code#15553, "Working Workaround #2").

Caveats:

• Still need send-keys for Enter/Escape (small payloads, much less likely to block)
• paste-buffer still writes through the PTY, so theoretically could block under extreme conditions
• Should use named buffers (-b) to avoid collisions between concurrent sessions

Verdict: Best near-term solution. Minimal code change, preserves full tmux architecture, and community-validated.

6. tmux pipe-pane -I — ❌ No improvement

Under the hood, pipe-pane -I uses the same PTY write path as send-keys. No meaningful difference.

7. tmux Control Mode (-CC) — ❌ Overkill

Still uses send-keys under the hood. Interesting for structured output notifications (could replace capture-pane polling) but doesn't solve the input problem.

---

Summary

Approach	TTY	Blocking	Ghost Msgs	Effort	Verdict
paste-buffer -p	✅	⚠️ Partial	✅	Low	Implement now
creack/pty	✅	✅	✅	High	Future architecture
FIFO stdin	❌	⚠️	✅	Low	Dead end
FIFO-to-PTY bridge	✅	✅	✅	High	Redundant w/ creack/pty
tmux fork	✅	⚠️	❌	High	Impractical
pipe-pane -I	✅	❌	❌	Low	No improvement
Control mode	✅	❌	❌	High	Overkill

Recommended Action Plan

Phase 1 (immediate):

1. Add context.WithTimeout to ALL send-keys calls as a safety net (prevents listener hang)
2. Switch sendToTmuxWithDelay() from send-keys -l to set-buffer + paste-buffer -p pattern
3. Keep send-keys only for small control keys (Enter, Escape, Down) which are unlikely to block

Phase 2 (if Phase 1 insufficient):

• Investigate creack/pty architecture for direct PTY control
• Would require a Go virtual terminal emulator for output parsing
• Significant rewrite but eliminates tmux from the critical I/O path entirely

[kidandcat]

Fix submitted: #14

Implements Phase 1 from the investigation:

• set-buffer + paste-buffer -p replaces all send-keys -l calls (bracketed paste avoids PTY buffer deadlock)
• context.WithTimeout(5s) on all remaining send-keys calls (control keys only)
• Zero unprotected exec.Command(tmuxPath, "send-keys", ...) calls remain

[kidandcat]

@MichaelC001 it would be great if you could test in deep this solution, as I'm not currently using CCC by myself (I moved to https://github.com/kidandcat/minerva)