kirby44/terminals

Terminals MCP Server

A Model Context Protocol (MCP) server for managing multiple persistent terminal sessions.

Features

• Create and manage multiple named terminal sessions
• Execute commands in specific sessions
• Persistent shell environments (env vars, working directory, history)
• Session output buffering and retrieval
• Clean session lifecycle management
• Default session support for convenience
• Visual session monitoring with Observer app (macOS)

Installation

npm install
npm run build

Usage

Available Tools

1. create_session - Create a new persistent terminal session

   • sessionId (string, required): Unique identifier for the session
   • shell (string, optional): Shell to use (default: system shell)
   • cwd (string, optional): Working directory (default: current directory)

2. list_sessions - List all active terminal sessions

3. execute_in_session - Execute a command in a specific session

   • sessionId (string, required): Session ID to execute command in
   • command (string, required): Command to execute

4. get_session_output - Get recent output from a session

   • sessionId (string, required): Session ID to get output from
   • lines (number, optional): Number of recent lines to retrieve

5. destroy_session - Destroy a terminal session

   • sessionId (string, required): Session ID to destroy

6. set_default_session - Set the default session for subsequent operations

   • sessionId (string, required): Session ID to set as default

Example Usage

// Create two sessions
create_session({ sessionId: "app" })
create_session({ sessionId: "client", cwd: "/tmp" })

// Start an app in session 1
execute_in_session({ sessionId: "app", command: "npm start" })

// Interact with the app from session 2
execute_in_session({ sessionId: "client", command: "curl http://localhost:3000" })

// Check what's running
list_sessions({})

// Get recent output
get_session_output({ sessionId: "app", lines: 20 })

// Cleanup
destroy_session({ sessionId: "client" })

Architecture

• Each session runs a persistent shell process in non-interactive mode
• Commands are sent to the shell via stdin
• Output is captured and buffered (max 1000 lines per session)
• Sessions maintain their own environment and working directory
• Proper cleanup ensures no orphaned processes
• Event listener management prevents memory leaks
• Error handling for robust operation with Claude Code

Stability & Reliability

This server has been tested and debugged for use with Claude Code. Key fixes include:

• Memory leak prevention: Proper event listener cleanup in command execution
• TTY compatibility: Non-interactive shell mode for pipe-based communication
• Error handling: Comprehensive error handling for file operations and process management
• Resource cleanup: Proper timing of process termination and directory cleanup

See ISSUE_MEMORY_LEAK.md for detailed technical information about stability improvements.

Observer App (macOS)

The observer/ directory contains a Swift macOS application for visual monitoring of terminal sessions in real-time. The Observer app provides:

• Grid and sidebar view modes for session display
• Real-time output monitoring through file watching
• Visual interface for tracking multiple terminal sessions

To run the Observer app:

cd observer
./run.sh

Development

npm install
npm run build
npm run dev  # Watch mode

License

MIT