terminalcp
https://github.com/badlogic/terminalcp- Category
- Developer Tools
- Rank
- No. 1587Tools index
Previous survey · No. 1594 ·
- Pricing
- Open Source
- Type
- TOOL
- Builder
- badlogic
- GitHub
- 124 stars
- Latest release
- v1.3.3
- Date
About
Lightweight terminal session manager and copy/paste helper by badlogic.
What it does
terminalcp lets AI agents operate interactive terminal programs through persistent pseudo-terminal sessions. An agent can launch commands, send text or special keys, inspect either the rendered terminal or raw incremental output, and manage several background processes. Humans can also attach to those sessions and interact directly.
Why it's ranked here
It is a compelling bridge between agents and tools built for human terminals. Proper terminal emulation supports debuggers, REPLs, full-screen interfaces, and long-running jobs. The dual output model is especially practical: agents can inspect visual state when layout matters, then switch to incremental text for logs.
What's good
Sessions survive MCP client disconnections and server restarts because a separate background process owns them. Rendered output preserves cursor movement and terminal formatting, while stream output can remove ANSI codes and return only unread data. Named sessions, live human attachment, synchronized resizing, and symbolic CLI key notation make difficult interactions manageable.
Tradeoffs
Commands run through a shell, so aliases do not work and command strings inherit shell execution risks. MCP callers must encode Enter, arrows, and control keys themselves. Sessions require manual cleanup and remain only while the background server lives. Raw stream history grows without a stated limit, while rendered scrollback is capped. Node.js 20 or newer is required.
How to use it well
Use it when an agent must drive a debugger, REPL, terminal interface, coding assistant, build, or server that cannot be handled by ordinary one-shot commands. Give sessions readable names, prefer rendered output for visual interfaces, use incremental streams for logs, and stop processes explicitly. Do not treat it as remote-host orchestration or a replacement for a full terminal multiplexer.
Technical notes+
src/terminal-manager.ts creates PTYs with node-pty, renders them through @xterm/headless, serializes terminal and PTY writes, stores raw output in memory, and keeps 10,000 lines of rendered scrollback. src/terminal-server.ts owns sessions and communicates over the user-only Unix socket ~/.terminalcp/server.sock; src/terminal-client.ts auto-starts that server only for start requests and rejects version mismatches. src/mcp-server.ts exposes one stdio MCP tool whose payload nests actions under args. src/index.ts supplies the CLI, while src/attach-client.ts handles raw terminal attachment, resize forwarding, backpressure, and Ctrl+B detachment. The README architecture text names ~/.terminalcp/server.socket, which differs from the .sock path used throughout the source.
Observed
- License
- MIT
- Primary language
- TypeScript, with a small C debugging fixture
- Packaging
- Published as the npm package @mariozechner/terminalcp with compiled JavaScript and TypeScript declarations
- Install surface
- Runs through npx or a global npm installation
- Interfaces
- Stdio MCP server, standalone CLI, and exported Node.js library types
- Runtime requirement
- Node.js 20 or newer
- Architecture
- Persistent local background server communicating through a user-only Unix domain socket
- Repository structure
- Includes an evaluation harness and a configured TypeScript test command
Read from README.md, package.json, src/index.ts, src/messages.ts, src/key-parser.ts, src/mcp-server.ts, src/attach-client.ts, src/terminal-client.ts, src/terminal-server.ts, src/terminal-manager.ts, test/eval/run.ts, test/demo-buggy.c, test/eval/stats.ts.
What it can do
Manage terminal sessions
Terminal commands and processes → Organized terminal session workspace
Copy text from terminal
Terminal text content → Text copied to clipboard
Paste text to terminal
Clipboard content → Text inserted into terminal session
Switch between terminal sessions
Session selection command → Active terminal session change
Create new terminal session
Session creation command → New terminal session instance
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.