Add tmux-compatible CLI semantics proposal for agent integration

[danshapiro]

Summary

This proposal document outlines a comprehensive strategy for providing tmux-compatible CLI semantics in Freshell, enabling AI coding agents to use Freshell as a drop-in replacement for tmux while also exposing Freshell-unique capabilities.

Key Changes

• Conceptual Model Mapping: Defines how tmux concepts (servers, sessions, windows, panes) map to Freshell equivalents, with sessions flattened to tabs for a single-user application model
• Command Mapping: Provides detailed translation of 40+ tmux commands to freshell equivalents, including:
  • Tab/window management (new-tab, kill-tab, list-tabs, etc.)
  • Pane operations (split-pane, send-keys, capture-pane, etc.)
  • Terminal I/O with precise key translation semantics
  • Introspection and display commands
• Freshell-Unique Features: Documents capabilities beyond tmux:
  • Browser pane control (open-browser, navigate)
  • Output-aware waiting (wait-for with pattern matching and stability detection)
  • Coding CLI integration (--claude, --codex flags)
  • Editor panes and AI summaries
  • Multi-pane orchestration primitives
• Target Addressing: Specifies Freshell's addressing format (tab.pane) with backward compatibility for tmux's session:window.pane syntax
• Implementation Architecture: Outlines required REST endpoints, scrollback buffer access, and optional MCP server
• Agent Discovery: Defines environment variables (FRESHELL, FRESHELL_URL, FRESHELL_TOKEN, etc.) for agent detection
• Phasing Strategy: Prioritizes implementation in 4 phases from MVP (send-keys, capture-pane) through ecosystem compatibility
• Design Rationale: Justifies key decisions (CLI-first approach, session flattening, wait-for as killer feature, server-side state management)
• Open Questions: Identifies architectural challenges (state ownership, multi-client coordination, active pane semantics, CLI distribution, authentication)

Notable Details

• send-keys semantics: Includes complete key name translation table matching tmux behavior (Enter, C-c, arrow keys, etc.)
• capture-pane output: Supports scrollback access with flags for line joining, ANSI stripping, and range selection
• wait-for enhancement: Proposes superior alternative to tmux's channel-based synchronization with pattern matching, stability detection, and prompt recognition
• Backward compatibility: Accepts tmux's session:window.pane format while using native tab.pane addressing
• Environment-based discovery: Agents detect Freshell via FRESHELL=1 environment variable, similar to tmux detection

This proposal establishes the foundation for making Freshell the preferred terminal multiplexer for AI agents while maintaining compatibility with existing tmux-based tools and orchestration frameworks.

https://claude.ai/code/session_015SDyBrYmnNcCPM8n2cdqqY

[danshapiro]

handling this locally