{"_id":"@antra_tessera/terminal-sessions-mcp","_rev":"3-98c3719e6235d8d3bf8eb695075435fd","name":"@antra_tessera/terminal-sessions-mcp","dist-tags":{"latest":"1.5.1"},"versions":{"1.4.0":{"name":"@antra_tessera/terminal-sessions-mcp","version":"1.4.0","keywords":["mcp","terminal","session","ai","assistant","pty","shell","persistent"],"author":{"name":"Anima Labs"},"license":"MIT","_id":"@antra_tessera/terminal-sessions-mcp@1.4.0","maintainers":[{"name":"antra_tessera","email":"antra@animalabs.ai"}],"homepage":"https://github.com/anima-labs/terminal-sessions-mcp#readme","bugs":{"url":"https://github.com/anima-labs/terminal-sessions-mcp/issues"},"bin":{"session-cli":"dist/cli/session-cli.js","session-gui":"dist/gui/src/start-gui.js","session-server":"dist/src/server/start-session-server.js","terminal-sessions-mcp":"dist/src/mcp/mcp-stdio-server.js"},"dist":{"shasum":"7f788a44453090bbb75b7d63baf6a3639962ad1b","tarball":"https://registry.npmjs.org/@antra_tessera/terminal-sessions-mcp/-/terminal-sessions-mcp-1.4.0.tgz","fileCount":66,"integrity":"sha512-BUJiOGLFdt0CWCHjao2MbTvWQWYabgEdG7IDYtP52bVTNe7wWjXKjF8PauMDGE0LBMSdS0snHeLNBsFUhmNcXg==","signatures":[{"sig":"MEUCIQDTT9PVXE1ZT1WTBjaXQNp9p2y6RkJOWbYBBx7t+dzc4gIgWXtU2UyROZRkLr8VBKZE5TmChGOF/Iddj2B2jVbxpR8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3062909},"main":"dist/src/index.js","types":"dist/src/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"efae3491e5e234a9623368bf9f2a82ac1f1c5e0f","scripts":{"cli":"ts-node cli/session-cli.ts","dev":"tsc --watch","build":"tsc","start":"node dist/src/server/start-session-server.js","start-gui":"ts-node gui/src/start-gui.ts","mcp-server":"ts-node src/mcp/mcp-stdio-server.ts","start-server":"ts-node src/server/start-session-server.ts","prepublishOnly":"npm run build","start-headless":"ts-node src/server/start-session-server.ts --headless"},"_npmUser":{"name":"antra_tessera","email":"antra@animalabs.ai"},"repository":{"url":"git+https://github.com/anima-labs/terminal-sessions-mcp.git","type":"git"},"_npmVersion":"11.3.0","description":"Persistent terminal session management with MCP integration for AI assistants","directories":{},"_nodeVersion":"24.1.0","dependencies":{"ws":"^8.16.0","express":"^5.1.0","node-pty":"^1.0.0","puppeteer":"^24.29.1","socket.io":"^4.8.1","strip-ansi":"^7.1.0","@xterm/xterm":"^5.5.0","ansi-to-html":"^0.7.2","@xterm/addon-fit":"^0.10.0","@xterm/addon-web-links":"^0.11.0","@modelcontextprotocol/sdk":"^1.11.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.0.0","@types/ws":"^8.5.10","typescript":"^5.0.0","@types/node":"^20.0.0","@types/express":"^5.0.5"},"_npmOperationalInternal":{"tmp":"tmp/terminal-sessions-mcp_1.4.0_1768688507219_0.49188091532512845","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@antra_tessera/terminal-sessions-mcp","version":"1.0.2","keywords":["mcp","terminal","session","ai","assistant","pty","shell","persistent"],"author":{"name":"Anima Labs"},"license":"MIT","_id":"@antra_tessera/terminal-sessions-mcp@1.0.2","maintainers":[{"name":"antra_tessera","email":"antra@animalabs.ai"}],"homepage":"https://github.com/antra-tess/terminal-sessions-mcp#readme","bugs":{"url":"https://github.com/antra-tess/terminal-sessions-mcp/issues"},"bin":{"session-cli":"dist/cli/session-cli.js","session-gui":"dist/gui/src/start-gui.js","session-server":"dist/src/server/start-session-server.js","terminal-sessions-mcp":"dist/src/mcp/mcp-stdio-server.js"},"dist":{"shasum":"bae087be51f8be63f8c4ed8c6b2bff7187bbb14d","tarball":"https://registry.npmjs.org/@antra_tessera/terminal-sessions-mcp/-/terminal-sessions-mcp-1.0.2.tgz","fileCount":51,"integrity":"sha512-DdvPv1p+d1WtYJ6ibP0+mg/ibVLAWmzSdI+Nr437c8Ixrga6CQ8hiDRrJ/8Z5GpW0ZcAF+fS9W7n+NcGtIPC5w==","signatures":[{"sig":"MEYCIQCNcDkXlZqTV/fFQ7aJRFr11qSfWqKJzUZPJlFjUL1IPwIhAKzUSeoXFmgood0t/b1Kmpsn5nfnjGWyZZ3Kj61XeWPa","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1650676},"main":"dist/src/index.js","types":"dist/src/index.d.ts","engines":{"node":">=18.0.0 <25.0.0"},"gitHead":"2fe31c59e6aa21e2e91117624afe37001aea48e0","scripts":{"cli":"ts-node cli/session-cli.ts","dev":"tsc --watch","build":"tsc","start":"node dist/src/server/start-session-server.js","start-gui":"ts-node gui/src/start-gui.ts","mcp-server":"ts-node src/mcp/mcp-stdio-server.ts","start-server":"ts-node src/server/start-session-server.ts","prepublishOnly":"npm run build","start-headless":"ts-node src/server/start-session-server.ts --headless"},"_npmUser":{"name":"antra_tessera","email":"antra@animalabs.ai"},"repository":{"url":"git+https://github.com/antra-tess/terminal-sessions-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Persistent terminal session management with MCP integration for AI assistants","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ws":"^8.16.0","express":"^5.1.0","node-pty":"^1.0.0","puppeteer":"^24.29.1","socket.io":"^4.8.1","strip-ansi":"^7.1.0","@xterm/xterm":"^5.5.0","ansi-to-html":"^0.7.2","@xterm/addon-fit":"^0.10.0","@xterm/addon-web-links":"^0.11.0","@modelcontextprotocol/sdk":"^1.11.2"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.0.0","@types/ws":"^8.5.10","typescript":"^5.0.0","@types/node":"^20.0.0","@types/express":"^5.0.5"},"_npmOperationalInternal":{"tmp":"tmp/terminal-sessions-mcp_1.0.2_1774713509741_0.008905799998110142","host":"s3://npm-registry-packages-npm-production"}},"1.5.1":{"name":"@antra_tessera/terminal-sessions-mcp","version":"1.5.1","description":"Persistent terminal session management with MCP integration for AI assistants","main":"dist/src/index.js","types":"dist/src/index.d.ts","bin":{"terminal-sessions-mcp":"dist/src/mcp/mcp-stdio-server.js","session-server":"dist/src/server/start-session-server.js","session-gui":"dist/gui/src/start-gui.js","session-cli":"dist/cli/session-cli.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/src/server/start-session-server.js","start-server":"ts-node src/server/start-session-server.ts","start-headless":"ts-node src/server/start-session-server.ts --headless","start-gui":"ts-node gui/src/start-gui.ts","mcp-server":"ts-node src/mcp/mcp-stdio-server.ts","cli":"ts-node cli/session-cli.ts","prepublishOnly":"npm run build"},"keywords":["mcp","terminal","session","ai","assistant","pty","shell","persistent"],"author":{"name":"Anima Labs"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/antra-tess/terminal-sessions-mcp.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.11.2","@xterm/addon-fit":"^0.10.0","@xterm/addon-web-links":"^0.11.0","@xterm/xterm":"^5.5.0","ansi-to-html":"^0.7.2","express":"^5.1.0","node-pty":"^1.0.0","puppeteer":"^24.29.1","socket.io":"^4.8.1","strip-ansi":"^7.1.0","ws":"^8.16.0"},"devDependencies":{"@types/express":"^5.0.5","@types/node":"^20.0.0","@types/ws":"^8.5.10","ts-node":"^10.0.0","typescript":"^5.0.0"},"engines":{"node":">=18.0.0 <25.0.0"},"_id":"@antra_tessera/terminal-sessions-mcp@1.5.1","gitHead":"29b731d2493ca1a7d9fca5d14a1ef7b407796444","bugs":{"url":"https://github.com/antra-tess/terminal-sessions-mcp/issues"},"homepage":"https://github.com/antra-tess/terminal-sessions-mcp#readme","_nodeVersion":"24.1.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-fYpuOzxaOwQ2sJvwelUFn6TIinzqfPguueStpbB4IOZyjNlEXJ0BZa89PbhDanoIocQhgzrwpS+hROstM9QxZg==","shasum":"822240a84c8aff51f9caa1b21e99374e7af81c76","tarball":"https://registry.npmjs.org/@antra_tessera/terminal-sessions-mcp/-/terminal-sessions-mcp-1.5.1.tgz","fileCount":49,"unpackedSize":269554,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAi+aeRb7poX88Zsx+7aZ75f+XF9sLkaHXelPiIgnbv3AiAYWpHn7Uec2MGWef8Z0hCktJGCyRMDS4MTw2axE8C6lg=="}]},"_npmUser":{"name":"antra_tessera","email":"antra@animalabs.ai"},"directories":{},"maintainers":[{"name":"antra_tessera","email":"antra@animalabs.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/terminal-sessions-mcp_1.5.1_1774713845935_0.38645879792861737"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-17T22:21:47.091Z","modified":"2026-03-28T16:04:06.235Z","1.4.0":"2026-01-17T22:21:47.506Z","1.0.2":"2026-03-28T15:58:29.937Z","1.5.1":"2026-03-28T16:04:06.094Z"},"bugs":{"url":"https://github.com/antra-tess/terminal-sessions-mcp/issues"},"author":{"name":"Anima Labs"},"license":"MIT","homepage":"https://github.com/antra-tess/terminal-sessions-mcp#readme","keywords":["mcp","terminal","session","ai","assistant","pty","shell","persistent"],"repository":{"type":"git","url":"git+https://github.com/antra-tess/terminal-sessions-mcp.git"},"description":"Persistent terminal session management with MCP integration for AI assistants","maintainers":[{"name":"antra_tessera","email":"antra@animalabs.ai"}],"readme":"# Terminal Sessions MCP\n\n**Interactive, persistent terminal sessions for AI assistants via Model Context Protocol**\n\n![Web GUI Demo](docs/screenshots/web-gui-demo.gif)\n\n## Why This Matters\n\nWhile many AI tools offer basic command execution, Terminal Sessions MCP provides unique capabilities:\n\n**What makes this different:**\n- **Sessions survive IDE restarts** - Unlike typical tools, your sessions persist even when you close Cursor/Claude Desktop\n- **Background tasks with log access** - Run dev servers, builds, or tests in background while retaining full access to their output\n- **True interactivity** - Send input to prompts, handle confirmations, respond to interactive tools\n- **Process control** - Send signals (Ctrl+C, Ctrl+Z) to gracefully manage long-running processes\n- **Stateful environment** - `cd`, `export`, and environment changes persist across commands\n- **Visual debugging** - Take screenshots of terminal output to debug TUI applications\n- **Context search** - Search through command history and output with regex\n\nYour AI assistant can now run servers in the background while working on other tasks, maintain persistent development environments, handle interactive workflows, and even build terminal UI applications with visual feedback.\n\n## MCP Features\n\n✅ **Truly Persistent Sessions** - Sessions survive Cursor/IDE restarts, keeping all state  \n✅ **Interactive Workflows** - Handle password prompts, confirmations, and interactive tools  \n✅ **Build & Debug TUIs** - Develop terminal UI apps with visual feedback via screenshots  \n✅ **Process Control** - Send signals (SIGINT, SIGTERM, SIGTSTP) to running processes  \n✅ **Stateful Shell** - `cd`, `export`, and other state changes persist across AI responses  \n✅ **Log Search** - Search through command history and output with regex and context  \n✅ **Service Management** - Start services with intelligent readiness detection  \n✅ **Smart Command Execution** - Detects when commands complete, handles long-running processes  \n✅ **Multi-Session Management** - Track multiple services/sessions by name  \n✅ **Terminal Screenshots** - Capture visually rich terminal output for debugging  \n✅ **Real-Time Streaming** - Watch output as it happens, not just final results  \n\n## Quick Start for AI Assistants\n\n### 1. Install\n\n**Option A: Global install (recommended)**\n```bash\nnpm install -g term-sessions-mcp\n```\n\n**Option B: Local install**\n```bash\nnpm install term-sessions-mcp\n```\n\n### 2. Start the Terminal Session Server\n\nThis is the backend server that actually manages your terminal sessions:\n\n**If installed globally:**\n```bash\nsession-server\n# Starts session server on port 3100 (with GUI on port 3200)\n```\n\n**If installed locally:**\n```bash\nnpx session-server\n```\n\n**Headless mode (no GUI):**\n```bash\nsession-server --headless\n```\n\n**Remote access (bind to all interfaces):**\n```bash\nsession-server --host 0.0.0.0 --token your-secret-token\n```\n\n**Keep this server running** in the background - your AI assistant will connect to it.\n\n### 3. Configure the MCP Bridge for Your AI\n\nThis connects your AI assistant (Cursor/Claude) to the session server:\n\n**For Cursor:**\n1. Open Cursor Settings\n2. Go to **Cursor Settings** → **MCP**  \n3. Click **\"Add Custom MCP\"**\n4. This will open an editor for your MCP configuration\n5. Add the following:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal-sessions\": {\n      \"command\": \"terminal-sessions-mcp\",\n      \"env\": {\n        \"SESSION_SERVER_PORT\": \"3100\"\n      }\n    }\n  }\n}\n```\n\n**For Claude Desktop:**\nAdd to your `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal-sessions\": {\n      \"command\": \"terminal-sessions-mcp\",\n      \"env\": {\n        \"SESSION_SERVER_PORT\": \"3100\"\n      }\n    }\n  }\n}\n```\n\n**If the above doesn't work**, you may need to use the full path. Find it with:\n```bash\nwhich terminal-sessions-mcp\n```\n\nThen use that path in your config:\n```json\n{\n  \"mcpServers\": {\n    \"terminal-sessions\": {\n      \"command\": \"/full/path/to/terminal-sessions-mcp\",\n      \"env\": {\n        \"SESSION_SERVER_PORT\": \"3100\"\n      }\n    }\n  }\n}\n```\n\n**Important Notes:** \n- **Make sure `session-server` is running** on port 3100 before starting Cursor/Claude\n- The `terminal-sessions-mcp` executable is the MCP bridge - Cursor/Claude runs it automatically\n- You don't need to run `terminal-sessions-mcp` manually - only run `session-server`\n\n### 4. Use with Your AI Assistant\n\nYour AI assistant now has access to these MCP tools:\n\n- `startService` - Start a service with readiness detection\n- `runCommand` - Execute a command in a session\n- `tailLogs` - Get recent output from a session  \n- `searchLogs` - Search through output with regex\n- `sendInput` - Send input to interactive prompts\n- `sendSignal` - Send signals (Ctrl+C, etc.) to processes\n- `listSessions` - See all active sessions\n- `killSession` - Stop a session gracefully or forcefully\n- `takeScreenshot` - Capture terminal visual state\n\n## Web GUI (Optional)\n\nThe server includes an optional web-based GUI for human operators to monitor and interact with sessions:\n\n**Features:**\n- 📊 Dashboard showing all active sessions with live status\n- 🖥️ Full xterm.js terminal emulator with 256-color support\n- 🖱️ Complete mouse support in TUI apps (Midnight Commander, htop, etc.)\n- ⌨️ Direct keyboard input with proper key code forwarding\n- 📐 Automatic resize handling for perfect coordinate mapping\n- 🎨 Beautiful GitHub-inspired dark theme\n- 🔄 Real-time output streaming\n- ⚡ Signal controls (Ctrl+C, Ctrl+Z, SIGTERM)\n\n**Access:** Open `http://localhost:3200` when running with GUI enabled (default), or use `--headless` to disable.\n\n## TUI Control Sequences Support\n\nAll terminal control sequences work perfectly, enabling rich TUI applications:\n\n[![TUI Controls](docs/screenshots/tui-controls.png)](docs/screenshots/tui-controls.png)\n\n- ✅ **Cursor positioning** - `\\033[row;colH`\n- ✅ **Screen clearing** - `\\033[2J\\033[H`\n- ✅ **Colors & formatting** - All ANSI codes (30-37, 40-47, bold, dim, etc.)\n- ✅ **Progress bars** - Dynamic updates with proper positioning\n- ✅ **Box drawing** - UTF-8 box characters (╔═══╗)\n- ✅ **Live TUIs** - htop, vim, tmux, custom TUI apps\n\n## API Usage\n\n### From TypeScript/JavaScript\n\n```typescript\nimport { SessionClient } from 'term-sessions-mcp';\n\nconst client = new SessionClient('ws://localhost:3100');\n\n// Create a session\nawait client.createSession({ id: 'my-session' });\n\n// Execute commands\nconst result = await client.exec('my-session', 'npm test');\nconsole.log(result.output);\n\n// Search logs\nconst matches = await client.searchLogs('my-session', 'error|warning', 5);\n\n// Take a screenshot (includes all colors and formatting!)\nconst screenshot = await client.takeScreenshot('my-session', {\n  lines: 50,\n  outputPath: './terminal.png'\n});\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│      Web GUI (http://localhost:3200)            │\n│  - xterm.js terminal rendering                  │\n│  - Live Socket.IO updates                       │\n│  - Session dashboard                            │\n└─────────────────────────────────────────────────┘\n                     ↕ Socket.IO\n┌─────────────────────────────────────────────────┐\n│    Session Server (ws://localhost:3100)         │\n│  - PTY-based persistent sessions                │\n│  - WebSocket API                                │\n│  - Event streaming                              │\n└─────────────────────────────────────────────────┘\n                     ↕ MCP Protocol\n┌─────────────────────────────────────────────────┐\n│       AI Assistant (Cursor, Claude, etc.)       │\n│  - 10 MCP tools for session management          │\n│  - Start services, run commands                 │\n│  - Take screenshots                             │\n└─────────────────────────────────────────────────┘\n```\n\n## Available Tools (MCP)\n\nOnce configured, your AI assistant will have access to these tools:\n\n### Session Management\n- **startService** - Start a long-running service with startup detection\n- **runCommand** - Execute a command and wait for completion\n- **listSessions** - Get all active sessions\n- **killSession** - Terminate a specific session (graceful by default)\n- **killAll** - Terminate all active sessions\n\n### Interactive Operations\n- **sendInput** - Send input to a running process\n- **sendSignal** - Send a signal (SIGINT, SIGTERM, etc)\n\n### Log Operations\n- **tailLogs** - Get recent logs from a session\n- **searchLogs** - Search logs with regex patterns and context\n- **takeScreenshot** - Capture terminal screenshot with proper TUI rendering 📸\n\n## CLI Usage\n\nThe package includes a CLI tool for manual session management:\n\n```bash\n# List sessions\nnpx session-cli list\n\n# Create a session\nnpx session-cli create my-session --cwd=/path/to/dir\n\n# Execute a command\nnpx session-cli exec my-session \"npm test\"\n\n# Tail logs\nnpx session-cli tail my-session --lines=100\n\n# Subscribe to live events\nnpx session-cli subscribe my-session --replay=50\n```\n\n## Web GUI Usage\n\nStart the web GUI to visually manage all your terminal sessions:\n\n```bash\n# Start on default port (3200)\nnpx session-gui\n\n# Or custom port\nGUI_PORT=8080 npx session-gui\n```\n\nThen open http://localhost:3200 in your browser to:\n- View all active sessions in a sidebar\n- Click any session to see its xterm.js rendered terminal\n- Type commands directly in the web interface\n- Watch live updates stream in real-time\n- Take screenshots from the rendered terminal\n- Monitor multiple services simultaneously\n\n## Terminal Screenshots 📸\n\nPerfect for debugging visually rich terminal applications:\n\n```typescript\n// Capture a TUI, progress bar, or ANSI art\nconst result = await client.takeScreenshot('my-session', {\n  lines: 50,           // How many lines to capture\n  outputPath: './screenshot.png',  // Save to file\n  width: 1200,         // Image width\n  height: 800          // Image height\n});\n\n// Or get base64 (omit outputPath) - displays inline in MCP!\nconst { base64 } = await client.takeScreenshot('my-session');\n```\n\n**Use cases:**\n- 📊 Debugging progress bars and spinners\n- 🎨 Capturing ANSI art and colors\n- 🖥️  Visual regression testing of CLI tools\n- 📝 Documenting terminal applications\n- 🔍 Sharing colorized logs with proper formatting\n\n## Use Cases\n\n### 1. AI-Assisted Development\n\nEnable AI assistants to manage development services, run tests, and interact with terminal sessions without losing context between responses.\n\n### 2. Multi-Service Testing\n\nStart and monitor multiple services simultaneously, with intelligent startup detection and log search.\n\n### 3. Visual Terminal Debugging\n\nCapture screenshots of TUIs, progress bars, and ANSI art for debugging or documentation. The web GUI provides real-time visual feedback.\n\n### 4. Interactive Debugging\n\nAI assistants can interact with running processes, send input, and observe output in real-time.\n\n### 5. Team Collaboration\n\nShare terminal sessions between multiple agents or humans. Send a URL to view live terminal output.\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/antra-tess/terminal-sessions-mcp.git\ncd terminal-sessions-mcp\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Start session server\nnpm run start-server\n\n# Start web GUI\nnpm run start-gui\n\n# Run CLI\nnpm run cli -- list\n\n# Run demos\nnpx ts-node examples/screenshot-demo.ts\nnpx ts-node examples/service-management.ts\n```\n\n## Requirements\n\n- **Node.js** 18.x, 20.x, or 22.x LTS (Node 25+ not yet supported due to node-pty compatibility)\n- **Headless Chrome** (via Puppeteer) for screenshots\n- **Modern browser** for web GUI (Chrome, Firefox, Safari, Edge)\n\n## Configuration\n\n### Environment Variables\n\n**Server:**\n- `SESSION_SERVER_PORT` - WebSocket session server port (default: 3100)\n- `SESSION_SERVER_HOST` - Host to bind to (default: localhost)\n- `SESSION_SERVER_TOKEN` - Authentication token (optional, recommended for remote access)\n- `GUI_PORT` - Web GUI port (default: 3200)\n\n**MCP Client:**\n- `SESSION_SERVER_URL` - Full WebSocket URL (e.g., `ws://192.168.1.100:3100`)\n- `SESSION_SERVER_HOST` - Remote host (alternative to full URL)\n- `SESSION_SERVER_PORT` - Remote port (default: 3100)\n- `SESSION_SERVER_TOKEN` - Authentication token (must match server)\n- `MCP_DEBUG` - Enable debug logging (set to \"1\")\n\n### Remote Connections\n\nYou can connect to a session server running on a different machine:\n\n**On the remote machine:**\n```bash\nsession-server --host 0.0.0.0 --token mysecrettoken\n```\n\n**In your MCP config (local machine):**\n```json\n{\n  \"mcpServers\": {\n    \"terminal-sessions-remote\": {\n      \"command\": \"terminal-sessions-mcp\",\n      \"env\": {\n        \"SESSION_SERVER_URL\": \"ws://192.168.1.100:3100\",\n        \"SESSION_SERVER_TOKEN\": \"mysecrettoken\"\n      }\n    }\n  }\n}\n```\n\nYou can configure multiple MCP servers to connect to different machines simultaneously.\n\n## Troubleshooting\n\n### MCP server not loading\n\n1. Ensure the session server is running: `npx session-server`\n2. Check that paths in mcp.json are absolute\n3. Restart your AI assistant after configuration changes\n4. Enable debug mode: `MCP_DEBUG=1`\n\n### Web GUI not connecting\n\n1. Ensure session server is running on port 3100\n2. Check browser console for errors\n3. Verify Socket.IO and xterm.js CDN libraries loaded\n4. Try a different port if 3200 is occupied\n\n### Screenshots failing\n\n1. Ensure Puppeteer can launch headless Chrome\n2. Check system resources (memory)\n3. Try with fewer lines: `lines: 20`\n\n## License\n\nMIT\n\n## Credits\n\nDeveloped by [Anima Labs](https://github.com/anima-labs) as part of the Connectome project.\n\nExtracted as a standalone package because terminal session management with proper TUI support is universally useful for AI-assisted development workflows.\n\n## Contributing\n\nContributions welcome! Please open an issue or PR on GitHub.\n\n---\n\n**Star ⭐ this repo if you find it useful!**\n","readmeFilename":"README.md"}