Reference Implementation: Interactive PTY Management from Gemini CLI (Apache 2.0)

[zenyr]

📚 Reference Implementation Available

Discovered an excellent reference implementation for interactive PTY management in Gemini CLI (Apache 2.0 licensed).

Project

• Name: Gemini CLI
• Repository: https://github.com/google-gemini/gemini-cli
• License: Apache License 2.0 (permissive)

Implementation Details

The Gemini CLI project contains a sophisticated Interactive PTY Management System (ShellExecutionService) that demonstrates production-grade patterns for:

1. Dual PTY Architecture

• Primary: @lydell/node-pty with platform-specific pre-built binaries
• Fallback: Generic node-pty implementation
• Platform support: Windows (ARM64/x64), macOS (ARM64/x64), Linux (x64)

2. Bidirectional I/O Pipeline

• Input: writeToPty(pid, input) - ANSI sequence conversion & transmission
• Output: onData() callback → headlessTerminal.write() → ANSI parsing
• Real-time event streaming with structured output types

3. Headless Terminal Integration

• Uses @xterm/headless for ANSI escape sequence parsing
• Maintains separate physical (PTY) and logical (headless) terminal representations
• Advanced color/attribute extraction via serializeTerminalToObject()

4. Concurrency & Performance Optimization

• Processing chain: Promise chaining for sequential output guarantee
• Render throttling: 68ms debouncing (~14.7 FPS) for performance
• isWriting flag: Prevents concurrent terminal write operations
• hasStartedOutput: Skips rendering empty initialization output

5. Process Control Methods

• writeToPty(pid, input) - Send input/commands
• resizePty(pid, cols, rows) - Handle terminal resize (SIGWINCH)
• scrollPty(pid, lines) - Scrollback buffer control
• isPtyActive(pid) - Process existence verification

6. Cross-Platform Handling

• Windows: taskkill for process termination, code page detection
• Unix: Process group management (negative PID), SIGTERM→SIGKILL sequence
• Flow Control: XON/XOFF (Ctrl+S/Q) support

Key File References

packages/core/src/services/
  └─ shellExecutionService.ts          [Main implementation]

packages/core/src/utils/
  ├─ getPty.ts                         [PTY library loading strategy]
  ├─ shell-utils.ts                    [Platform-specific shell config]
  ├─ systemEncoding.ts                 [Windows code page support]
  └─ terminalSerializer.ts             [ANSI color extraction]

Documentation

An extensive technical analysis has been conducted covering:

• PTY initialization and process spawning
• Bidirectional I/O pipeline mechanics
• ANSI rendering and output extraction
• Output event system and state management
• Concurrency patterns and performance optimization
• Windows-specific implementation details

Potential Value for MCP-PTY

This implementation could serve as a reference for:

1. Handling complex PTY lifecycle management
2. Cross-platform compatibility patterns
3. Dual fallback strategy for PTY libraries
4. Performance-optimized output streaming
5. Interactive shell session control in Node.js

---

Note: This is submitted by Claude (Anthropic's Claude Haiku 4.5 model) as an informational reference for the community.

[zenyr]

📌 Related Gemini CLI PRs

Core Implementation: PR #6491 - Refactor Shell Execution to Use node-pty

PR: google-gemini/gemini-cli#6491
Status: Merged (2025-08-19)
Title: feat(core): refactor shell execution to use node-pty

Key Technical Achievements

This PR introduced the foundational architecture for Interactive PTY in Gemini CLI:

1. Problem Statement

   • Previous child_process.spawn implementation struggled with ANSI escape codes
   • Separate stdout/stderr streams caused race conditions and out-of-order output
   • Unreliable binary vs. text stream detection

2. Solution Architecture

   • node-pty Integration: Spawns processes within pseudo-terminal (like VS Code's terminal)
   • @xterm/headless: Interprets raw PTY output, correctly processes ANSI codes
   • Graceful Fallback: Dynamic loading of @lydell/node-pty → node-pty → child_process
   • Robust Termination: Process group management for clean child process cleanup

3. Implementation Details

   • Single, ordered output stream from PTY instead of racing stdout/stderr
   • Faithful terminal emulation matching user's actual terminal experience
   • Process group killing on Unix/macOS (negative PID) for proper cleanup
   • Binary data detection and mode switching

4. Core Service: ShellExecutionService

   • Main execution entry point with fallback strategy
   • Headless terminal buffer management
   • ANSI escape sequence parsing and rendering

Code References

// Primary: @lydell/node-pty (platform-specific pre-built)
// Fallback: node-pty (generic)
// Ultimate Fallback: child_process

const ptyInfo = await getPty();
const ptyProcess = ptyInfo.module.spawn(executable, args, {
  cwd,
  name: 'xterm',
  cols, rows,
  handleFlowControl: true,
});

This PR established the technical foundation for Interactive PTY management in Gemini CLI.

[zenyr]

Comparative Analysis: mcp-pty vs. Gemini CLI PTY Architecture

Author: Claude Haiku 4.5 (Anthropic)

Architectural Similarities

1. Headless Terminal Integration

Both projects use @xterm/headless for ANSI escape sequence parsing:

• Gemini CLI: @xterm/headless → serializeTerminalToObject() for color extraction
• mcp-pty: @xterm/headless → Terminal class for buffer capture via captureBuffer()

2. Event-Driven I/O Pipeline

• Gemini CLI: Promise-chained processing with render throttling (68ms debouncing)
• mcp-pty: Subscription-based pattern (subscribe()) with immediate event emission

3. Cross-Platform PTY Management

• Gemini CLI: @lydell/node-pty (pre-built) → node-pty → child_process fallback
• mcp-pty: @zenyr/bun-pty (Bun native) with no fallback chain

---

Key Architectural Differences

Feature	Gemini CLI	mcp-pty
PTY Library	node-pty (Node.js)	@zenyr/bun-pty (Bun native)
I/O Model	Dual stream (stdout/stderr merged)	Single PTY stream
Render Strategy	68ms throttle (~14.7 FPS)	Immediate event subscription
Output Buffer	Unbounded terminal history	Bounded 64KB max (safety)
Process Control	writeToPty(), resizePty(), scrollPty()	writeInput(), resize()
Termination	Process group (Unix), taskkill (Windows)	Bun process signals
Input Validation	Minimal (ANSI conversion only)	Strict (dangerous control sequence detection)
Session Management	Per-process state in ShellExecutionService	Centralized SessionManager + PtyManager

---

Production-Grade Patterns Worth Adopting

From Gemini CLI:

1. Dual Fallback Strategy - Graceful degradation across platforms/library availability
2. Render Throttling - Performance optimization for high-frequency output (68ms debounce)
3. Process Group Management - Proper cleanup of child process trees on Unix

mcp-pty Strengths:

1. Safety-First Input Validation - Blocks dangerous ANSI sequences (cursor positioning, screen clearing)
2. Bounded Memory Model - 64KB buffer prevents unbounded LLM context growth
3. Strict Session Isolation - Per-session PtyManager prevents cross-session interference
4. MCP Integration - Resource-based interface (pty:// URIs) vs. direct API calls

---

Potential Enhancement Opportunities

1. Output Debouncing - Consider 50-100ms render throttling for high-frequency commands
2. Scrollback Control - Add explicit scrollback buffer management (like scrollPty())
3. Cross-Platform Resilience - Evaluate library fallback chain for broader OS support
4. Performance Metrics - Add render frequency/latency tracking similar to Gemini CLI's approach

---

Context: This analysis identifies architectural alignment while highlighting mcp-pty's unique safety-first approach and bounded resource model—critical for LLM-driven terminal interactions.

[zenyr]

🔍 Upstream Analysis & Action Plan

Status: @zenyr/bun-pty foundation is solid. Identified optimization candidates, no architectural blockers.

Upstream @zenyr/bun-pty Assessment

✅ Strengths

• Multi-platform binaries (Linux/macOS/Windows, x64/ARM64)
• Exit code handling & FFI binding fixes already merged
• Clear error messages + custom library path support (BUN_PTY_LIB)

🎯 Optimization Opportunities (not required, but valuable)

1. Render Throttling: Gemini CLI's 68ms debounce (~14.7 FPS) could improve high-frequency output handling
2. Scrollback API: Add optional buffer limit methods (e.g., scrollback(lines)) similar to Gemini's scrollPty()
3. Fallback Chain Resilience: Consider @lydell/node-pty → node-pty pattern for broader platform coverage

mcp-pty Competitive Advantages

• Safety-first: Blocks dangerous ANSI sequences (cursor positioning, screen clearing)
• Bounded resource model: 64KB buffer cap prevents unbounded LLM context growth
• Session isolation: MCP resource URIs (pty://) provide cryptographic session boundaries

Sub-issues Created

→ See linked issues for detailed action items on render optimization, scrollback API, and design documentation.

Verdict: Current architecture supports LLM-driven terminal interactions safely. Reference implementation confirms best practices already in use.

[zenyr]

📖 Reference: Google Developers Blog - "Say hello to a new level of interactivity in Gemini CLI"

Blog Post: https://developers.googleblog.com/en/say-hello-to-a-new-level-of-interactivity-in-gemini-cli/
Published: October 15, 2025

Alignment with mcp-pty Architecture

The Google Blog reveals that Gemini CLI adopted serialization-first design—the same proven approach already implemented in mcp-pty. This validates your architecture decisions.

✅ Validated Approach: Terminal Serialization

Google's "live feed" concept (snapshot-based streaming) aligns with mcp-pty's core:

Gemini CLI (Real-time TUI)       mcp-pty (Async MCP)
─────────────────────────────────────────────────────
PTY Output → xterm/headless  →  Serializer → JSON URIs
                Snapshot          (pty://{id}/output)
                                      ↓
                            Persistent session state
                            (across client requests)

Key difference: mcp-pty's resource-based interface (pty:// URIs) abstracts the serialized state for MCP consumption, enabling true async querying without assuming persistent connection.

2️⃣ Long-Running Detection (What Gemini CLI Does Well)

Google Blog: "gracefully handle vim/top/less without hanging"

Gemini CLI's mechanism (from PR #6491):

• Binary detection: First 4KB sniff determines text vs. interactive mode
• Output rate analysis: Monitors data flow to distinguish idle vs. active
• Event-driven: onData/onExit callbacks enable graceful transitions

For mcp-pty: This binary detection + state machine pattern could enhance:

• Determining when PTY is truly interactive (vim) vs. just slow (compilation)
• Appropriate streaming strategy selection
• Session idle timeout heuristics

3️⃣ Dual Transport as Extended Pattern

Gemini CLI: Single terminal, persistent connection
mcp-pty: Dual transport (stdio + HTTP) with SSE

This extends the serialization pattern:

• stdio: 1:1 binding (like Gemini CLI's TUI)
• HTTP: Stateless resource queries + SSE notifications for state updates
• Sessions: Persistent across multiple client requests

This is a superset of Gemini CLI's architecture—preserving serialization benefits while enabling MCP's multi-client, stateless constraint.

4️⃣ Session Persistence (mcp-pty Advantage)

Gemini CLI: Single-session context within one CLI instance
mcp-pty: Multiple independent sessions with ULID-based tracking

// Gemini CLI: Single PTY per session
this.activePtys = new Map<number, ActivePty>();

// mcp-pty: Multiple sessions, each with multiple PTYs
resources: [
  "pty://status",
  "pty://list",
  "pty://{sessionId}/output",
  "pty://{processId}/status"
]

This enables context preservation across LLM turns—a key MCP advantage over Gemini CLI's single-session model.

Comparative Insights

Aspect	Gemini CLI	mcp-pty	Trade-off
Architecture	Real-time TUI	Async MCP server	Immediacy vs. Composability
Serialization	Per-frame snapshots	Resource-based state	Stream vs. Query
Sessions	1:1 CLI instance	Multi-session, persistent	Context depth vs. Scalability
Transport	Persistent connection	Dual (stdio/HTTP)	Simplicity vs. Flexibility
LLM Integration	Native (Gemini API)	Via MCP tools	Tight vs. Decoupled

Implications for mcp-pty Development

Strengths to leverage:

1. Serialization-first is proven (now with Google's validation)
2. Persistent sessions enable richer context preservation
3. Dual transport makes it universally compatible
4. ULID-based session tracking is clean and scalable

Areas for enhancement (inspired by Gemini CLI's refinements):

1. Long-running detection: Binary detection + rate analysis for better heuristics
2. Input queuing: Graceful handling of commands during PTY initialization
3. SIGWINCH support: Real-time terminal resize notifications via SSE
4. Color attribute preservation: Detailed ANSI attribute tracking for rich rendering

Note: Gemini CLI's approach of maintaining a headless terminal buffer (@xterm/headless) for rendering could be adapted in mcp-pty for more sophisticated PTY state queries, but the serialization abstraction you've already chosen is arguably more MCP-native.