NPCterm

The ultimate harness agent tool. A headless, in-memory terminal emulator for AI agents, exposed via MCP (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.

Features

• Full ANSI/VT100 terminal emulation with PTY spawning via portable-pty
• 15 MCP tools for complete terminal control over JSON-RPC stdio
• 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, selection, and scroll support for interacting with TUI applications
• Multiple concurrent terminals with short 2-character IDs

Install

Option 1: Install with Cargo (recommended)

cargo install npcterm

This installs npcterm to your Cargo bin directory (usually ~/.cargo/bin/), making it available system-wide.

Option 2: Download pre-built binaries

Pre-built binaries are available in the dist/ directory for:

• macOS ARM64 (Apple Silicon) / x64 (Intel)
• Linux ARM64 / x64
• Windows x64

Download the binary for your platform and place it somewhere in your PATH.

Option 3: Build from source

cargo build --release

The binary will be at target/release/npcterm.

OpenClaw

OpenClaw has built-in MCP support. First install NPCterm:

cargo install npcterm

Then register it as an MCP server:

openclaw mcp set npcterm '{"command":"npcterm","args":[]}'
openclaw gateway restart

Or add it manually to ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "npcterm": {
        "command": "npcterm",
        "args": []
      }
    }
  }
}

If you downloaded a pre-built binary instead, use the full path:

openclaw mcp set npcterm '{"command":"/path/to/npcterm","args":[]}'

Once registered, all 15 NPCterm tools will be available to your OpenClaw agent as npcterm__terminal_create, npcterm__terminal_send_keys, etc.

Verify the server is registered with:

openclaw mcp list

Claude Desktop / Claude Code

First install NPCterm:

cargo install npcterm

Then add it to your MCP configuration:

{
  "mcpServers": {
    "npcterm": {
      "command": "npcterm"
    }
  }
}

If you downloaded a pre-built binary instead, use the full path as the "command" value.

Usage

NPCterm is an MCP server. It communicates over stdin/stdout using JSON-RPC. To use it, configure it as an MCP server in your AI agent's MCP configuration (see install instructions above).

Available Tools

Example: Yes, your agent now can quit Vim

// MCP Flow
// 1. Create a terminal
// -> terminal_create {}
// <- {"id": "a0", "cols": 80, "rows": 24}

// 2. Open vim
// -> terminal_send_keys {"id": "a0", "input": [{"text": "vim"}, {"key": "Enter"}]}
// <- {"success": true}

// 3. Read the screen to confirm vim is open
// -> terminal_show_screen {"id": "a0"}
// <- ~                              VIM - Vi IMproved
// <- ~                               version 9.2.250
// <- ~                           by Bram Moolenaar et al.
// <- ~                type  :q<Enter>               to exit
// <- ...

// 4. Quit vim (the hard part, apparently)
// -> terminal_send_keys {"id": "a0", "input": [{"text": ":q"}, {"key": "Enter"}]}
// <- {"success": true}

// Back at the shell. First try.

NPCterm39 gives AI agents full TUI interaction: opening, navigating, and closing interactive programs like vim, htop, less, or any curses-based application.

Example: btop running inside NPCterm, controlled by an agent

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

Architecture

MCP Server (stdio JSON-RPC)
       |
  Tool Handlers (15 tools)
       |
  TerminalRegistry (concurrent terminal management)
       |
  TerminalInstance (emulator + mouse + selection + events)
       |
  TerminalEmulator (PTY spawn, I/O threads, grid)
    |-- TerminalGrid (screen buffer, scrollback, dirty tracking)
    |   '-- AnsiHandler (VTE parser)
    |-- TerminalCell (character + style attributes)
    '-- PTY (portable-pty)

Each terminal spawns a background PTY reader thread. A global tick thread (10ms interval) drains PTY output through the VTE parser, detects process state changes, and emits events.

Engine

Ported from project term39

Security Considerations

NPCterm provides unrestricted shell access to whatever agent connects to it. Before deploying:

• Sandbox the environment. Run inside containers, VMs, or other isolation boundaries.
• Limit the agent's permissions. Use restricted user accounts, filesystem permissions, and network policies.
• Monitor activity. Log terminal events and review agent behavior.
• Do not run as root. The PTY inherits the permissions of the NPCterm process.
• Treat this as you would SSH access. If you wouldn't give the agent an SSH session to the machine, don't give it NPCterm either.

License

Apache 2