shell-integration

Shell Integration

Sidecar's interactive shell allows users to type directly into tmux sessions from within the TUI. It is NOT a terminal emulator -- tmux is the PTY backend, sidecar acts as an input/output relay.

Package Structure

internal/tty/                    # Shared tmux terminal abstraction
  tty.go                         # Core Model and State types
  keymap.go                      # Bubble Tea -> tmux key translation
  messages.go                    # Message types (CaptureResultMsg, PollTickMsg, etc.)
  session.go                     # tmux operations (send-keys, capture-pane, resize)
  polling.go                     # Polling interval constants and calculation
  cursor.go                      # Cursor rendering and position query
  paste.go                       # Paste handling (clipboard, bracketed paste)
  terminal_mode.go               # Terminal mode detection (mouse, bracketed paste)
  output_buffer.go               # Thread-safe buffer with hash-based change detection

internal/plugins/workspace/
  interactive.go                 # Workspace-specific interactive mode logic
  interactive_selection.go       # Text selection in interactive mode
  view_preview.go                # Rendering with cursor overlay and scroll offset
  mouse.go                       # Scroll handling
  types.go                       # InteractiveState type

internal/plugins/filebrowser/
  inline_edit.go                 # Inline editor mode using tty.Model
  handlers.go                    # Message handling for inline edit

Data Flow

User Keypress -> handleInteractiveKeys()
              -> tty.MapKeyToTmux()
              -> tmux send-keys
              -> schedulePoll(20ms debounce)
              -> capture-pane + cursor query
              -> CaptureResultMsg
              -> OutputBuffer.Update()
              -> pollInteractivePane() (adaptive 50-250ms)
              -> renderWithCursor()

Core Abstractions

tty.Model

Embeddable component for interactive tmux functionality:

type Model struct {
    Config   Config        // Exit key, copy/paste keys, scrollback lines
    State    *State        // Current interactive state
    Width    int
    Height   int
    OnExit   func() tea.Cmd
    OnAttach func() tea.Cmd
}

// Usage:
p.inlineEditor = tty.New(&tty.Config{
    ExitKey: "ctrl+\\",
    ScrollbackLines: 600,
})
cmd := p.inlineEditor.Enter(sessionName, paneID)

tty.State

type State struct {
    Active        bool
    TargetPane    string      // tmux pane ID (e.g., "%12")
    TargetSession string
    LastKeyTime   time.Time   // For polling decay
    CursorRow, CursorCol int
    CursorVisible        bool
    PaneHeight, PaneWidth int
    BracketedPasteEnabled bool
    MouseReportingEnabled bool
    OutputBuf      *OutputBuffer
    PollGeneration int          // For invalidating stale polls
}

tty.OutputBuffer

Thread-safe bounded buffer with hash-based change detection:

func (b *OutputBuffer) Update(content string) bool {
    rawHash := maphash.String(seed, content)
    if rawHash == b.lastRawHash { return false }  // Skip ALL processing
    content = mouseEscapeRegex.ReplaceAllString(content, "")
    b.lines = strings.Split(content, "\n")
    return true
}
func (b *OutputBuffer) LinesRange(start, end int) []string

Key Mapping (keymap.go)

func MapKeyToTmux(msg tea.KeyMsg) (key string, useLiteral bool) {
    switch msg.Type {
    case tea.KeyEnter:     return "Enter", false
    case tea.KeyBackspace: return "BSpace", false
    case tea.KeyTab:       return "Tab", false
    case tea.KeyUp:        return "Up", false
    case tea.KeyCtrlC:     return "C-c", false
    case tea.KeyRunes:     return string(msg.Runes), true  // Literal mode
    }
}

Modified keys use CSI sequences:

case "shift+up":   return "\x1b[1;2A", true
case "ctrl+up":    return "\x1b[1;5A", true
case "alt+up":     return "\x1b[1;3A", true
case "shift+tab":  return "\x1b[Z", true

For printable characters, tmux send-keys -l prevents interpretation.

Adaptive Polling (polling.go)

const (
    PollingDecayFast   = 50ms    // During active typing
    PollingDecayMedium = 200ms   // After 2s inactivity
    PollingDecaySlow   = 250ms   // After 10s inactivity
    KeystrokeDebounce  = 20ms    // Delay after keystroke
)

Three-State Visibility Polling (Workspace)

Poll Generation

Stale polls invalidated using generation counter:

func (m *Model) schedulePoll(delay time.Duration) tea.Cmd {
    m.State.PollGeneration++
    gen := m.State.PollGeneration
    return tea.Tick(delay, func(t time.Time) tea.Msg {
        return PollTickMsg{Generation: gen}
    })
}

Performance Per Keystroke

1. tmux send-keys (~10ms)
2. 20ms debounce
3. capture-pane (~5ms) + cursor query (~5ms)
4. Hash check (~1ms), regex if changed (~5ms), buffer split (~1ms)
5. Cursor overlay (<1ms)

Total: ~42ms worst case, ~36ms typical.

Cursor Positioning (cursor.go)

Query

func QueryCursorPositionSync(target string) (row, col, paneHeight, paneWidth int, visible, ok bool) {
    cmd := exec.Command("tmux", "display-message", "-t", target,
        "-p", "#{cursor_x},#{cursor_y},#{cursor_flag},#{pane_height},#{pane_width}")
}

Rendering

Cursor is rendered as a block character overlaid on captured output. Handles cursor past end of line (pad with spaces) and cursor within line (ANSI-aware slicing with ansi.Cut).

Height Mismatch Adjustment

When display height differs from tmux pane height:

if paneHeight > displayHeight {
    relativeRow = cursorRow - (paneHeight - displayHeight)
} else if paneHeight > 0 && paneHeight < displayHeight {
    relativeRow = cursorRow + (displayHeight - paneHeight)
}

Scrolling

Scrolling operates on the captured buffer. No tmux copy-mode involved.

type Plugin struct {
    previewOffset    int   // Lines from bottom (0 = at bottom/live)
    autoScrollOutput bool  // Auto-follow new output?
}

• Scroll UP: pause auto-scroll, increment previewOffset
• Scroll DOWN: decrement previewOffset, re-enable auto-scroll at 0
• Bounded by capture window (default 600 lines)
• Instant response (pure state manipulation, no subprocess calls)

Copy/Paste

• Copy: alt+c (configurable via interactiveCopyKey)
• Paste: alt+v (configurable via interactivePasteKey)

Paste wraps text with bracketed paste sequences (\x1b[200~...\x1b[201~) when the application has enabled bracketed paste mode.

Terminal Mode Detection (terminal_mode.go)

Detects bracketed paste and mouse reporting modes by scanning output for enable/disable escape sequences. Latest enable > latest disable = mode active.

Width Synchronization

Tmux panes are resized in background at all times (not just interactive mode):

func ResizeTmuxPane(paneID string, width, height int) {
    // resize-window, fallback to resize-pane for older tmux
}

Resize triggers: window resize, sidebar toggle/drag, selection change, agent/shell creation, interactive mode entry.

Inline Edit Mode (Filebrowser)

Uses tty.Model for vim/nano/emacs editing in the file preview pane:

func (p *Plugin) enterInlineEditMode(path string) tea.Cmd {
    editor := os.Getenv("EDITOR")
    sessionName := fmt.Sprintf("sidecar-edit-%d", time.Now().UnixNano())
    exec.Command("tmux", "new-session", "-d", "-s", sessionName, editor, path).Run()
    return InlineEditStartedMsg{SessionName: sessionName}
}

Entry and Exit

Workspace Plugin:

• Enter: i when preview pane focused with output tab
• Exit: Ctrl+\ (instant) or double-Escape (150ms delay)
• Attach: Ctrl+] (full tmux attach)

Filebrowser Plugin:

• Enter: e or Enter on a file (if inline edit enabled)
• Exit: Ctrl+\ or double-Escape
• Attach: Ctrl+]

Feature Flags

{
  "features": {
    "tmux_interactive_input": true,
    "tmux_inline_edit": true
  }
}

Configuration

{
  "plugins": {
    "workspace": {
      "interactiveExitKey": "ctrl+\\",
      "interactiveAttachKey": "ctrl+]",
      "interactiveCopyKey": "alt+c",
      "interactivePasteKey": "alt+v",
      "tmuxCaptureMaxBytes": 600
    }
  }
}

Critical Rules

1. Never clear OutputBuffer -- breaks hash-based change detection and rendering
2. Always increment poll generation on entering interactive mode to avoid duplicate poll chains (causes 200% CPU)
3. Never call subprocesses from View() -- cursor queries and tmux ops must run in poll handlers
4. Don't mix shell/workspace polling -- shells use scheduleShellPollByName() + shellPollGeneration, workspaces use scheduleAgentPoll() + pollGeneration
5. Hash before regex -- massive CPU savings when content unchanged
6. Debouncing works -- 20ms delay reduces subprocess spam ~60%
7. Atomic cursor capture -- query cursor with output to avoid race conditions
8. Width sync matters -- resize panes in background at all times

References

• Tmux integration notes -- detailed tmux CLI techniques, cursor tracking, resize sync, bracketed paste, mouse forwarding, modified keys, adaptive polling, debugging
• Original spec: docs/spec-tmux-interactive-input.md