mcp-ssh-tmux: Instructions file for Codex

Agent Continuity Guide

Source Reference

• Reference Project: mcp-ssh-session
• Absolute Path: /home/jon/Dev/ai/mcp/mcp-ssh-session
• Status: Pivot complete. Logic ported and improved.

Current Infrastructure

• Environment: uv (Python 3.14+)
• Command Runner: just (see Justfile)
• Core Library: libtmux (v0.30+ API used) with isolated socket (socket_name="mcp-ssh")
• Logic: mcp_ssh_tmux/session_manager.py and server.py.

Technical Insights for Future Agents

Philosophy: LLM-as-Observer

• The server provides raw visual snapshots. The AI agent is responsible for interpreting state (prompts, errors, etc.).
• Hints: server.py appends [INFO: ...] hints to snapshots when common shell prompts or password requests are detected.

Async Polling (Critical)

• send_command and read_file MUST use await asyncio.sleep(), never time.sleep(). The MCP server runs on an async event loop (FastMCP/uvicorn). Synchronous sleep blocks the entire event loop, making the server unresponsive to all other requests during the polling period. This was the root cause of a production bug where send_command with large timeouts (e.g., 60s for docker service update) killed the server's ability to handle concurrent get_snapshot or list_sessions calls.

Key Dispatch

• send_keys (literal mode) uses pane.cmd("send-keys", *keys.split()) to pass each token as a separate tmux argument. This lets tmux interpret key names (Enter, C-c, Tab) while still sending unrecognized tokens as literal text.
• Do NOT use libtmux's literal=True — it passes -l to tmux, which disables all key name interpretation (e.g., "yes Enter" would type the word "Enter").

Connection Management

• SSH Execution: We start ssh directly as the window_shell command in tmux. This is more reliable than starting a shell and sending keys.
• Config Resolution: We use ssh -G <host> to resolve aliases and identity files from the user's ~/.ssh/config.
• Interactive Sessions: We intentionally avoid BatchMode=yes for the primary tmux-backed SSH session so the AI can handle interactive password/passphrase prompts visually.
• Direct File Reads: read_remote_file first attempts a separate non-interactive ssh -o BatchMode=yes ... cat -- <path> using the resolved host/user/port/key info. If that fails, it falls back to bounded tmux history capture.
• Persistence: remain-on-exit is enabled via window.set_option("remain-on-exit", "on"). This allows capturing final errors after a connection dies.