Npcterm

NPCterm

The ultimate harness agent tool. A headless, in-memory terminal emulator for AI agents, exposed via [MCP](https://modelcontextprotocol.io/) (Model Context Protocol).

NPCterm gives AI agents **full terminal access**. The ability to spawn shells, run arbitrary commands, read screen output, send keystrokes, and interact with TUI applications. This is one of the most powerful capabilities you can grant an AI agent: it is effectively equivalent to giving it access to a computer.

**Use with precautions.** A terminal is an unrestricted execution environment. Any command the agent can type, the system will run. This includes installing software, modifying files, accessing the network, and anything else a shell user can do. Deploy NPCterm in sandboxed or controlled environments, and always apply the principle of least privilege. Do not expose it to untrusted agents without appropriate safeguards.

Full system monitoring with `btop`, launched, read, and navigated entirely by an AI agent through MCP tools.

Features

• Full ANSI/VT100 terminal emulation with PTY spawning via portable-pty
• 17 MCP tools for complete terminal control over JSON-RPC stdio
• Built on TurboMCP 3.0 -- production-grade MCP SDK with auto-generated tool schemas
• Multi-version MCP protocol support -- compatible with clients using 2024-11-05, 2025-06-18, or 2025-11-25 spec versions
• Incremental screen reads with dirty-row tracking for efficient output consumption
• Process state detection: knows when a command is running, idle, waiting for input, or exited
• Event system: ring buffer of terminal events (CommandFinished, WaitingForInput, Bell, etc.)
• AI-friendly coordinate overlay for precise screen navigation
• **Mouse, select