termin8r

Claude Code MCP plugin for headless terminal automation — spawn interactive apps, read the screen, drive the keyboard and mouse. No GUI, no X server, no display needed.

termin8r-story.mov

Claude Code Plugin

Prerequisite: Rust toolchain (cargo and rustc).

Register the marketplace, then install:

# One-time: add the sdkks marketplace (use the repo URL, NOT the raw .json)
claude plugin marketplace add https://github.com/sdkks/termin8r

# Then install
claude plugin install termin8r

Or from a local clone:

git clone https://github.com/sdkks/termin8r.git
cd termin8r
cargo build --release --bin termin8r
claude mcp add termin8r -- target/release/termin8r

MCP Tools

The plugin registers as termin8r and exposes these tools:

• spawn — Start a terminal session with a command (shell defaults to true)
• screenshot — Capture the screen as text (default) or save a PNG to disk
• press — Send named keystrokes (Enter, F5, Ctrl+C, etc.)
• type_text — Type literal text
• paste — Paste text (bracketed-paste aware, safe for multi-line)
• mouse_click / mouse_drag / mouse_scroll — Drive the mouse
• mouse_click_text — Click on a label by its on-screen text
• wait — Block until a regex matches the screen or the screen stabilizes
• resize / scrollback / cursor_position — Inspect and control terminal state
• list_sessions / session_status / kill — Session management

Docker Sandbox (MCP Development)

Self-contained stack for developing and testing the MCP plugin. Rust toolchain, latest Claude Code, marketplace pre-registered, binary pre-built, plugin pre-installed:

cd docker/observability
docker compose up

This brings up:

• termin8r-sandbox — Ubuntu 24.04 with Rust, Claude Code, nano, neovim, and the plugin pre-installed
• OpenTelemetry Collector — receives traces from Claude Code, forwards to Jaeger
• Jaeger — trace query UI at http://localhost:16686
• Prometheus — metrics UI at http://localhost:9090

The sandbox connects to a local AI gateway via sdkks/7bridges (edit ANTHROPIC_BASE_URL in the compose file if your gateway is elsewhere):

ANTHROPIC_API_KEY: "ollama"
ANTHROPIC_BASE_URL: "http://host.docker.internal:4001"

Usage:

docker compose exec termin8r-sandbox bash
claude                          # plugin is pre-installed, MCP tools ready

Development

make install-pre-commit-hook    # install git hooks (symlinked — auto-update with script changes)

Hooks

• pre-commit — runs cargo fmt --check, cargo clippy, and cargo test before each commit
• commit-msg — validates the commit message follows conventional commit format (feat:, fix:, chore:, etc.). Required for semantic release via release-plz.

Hooks are installed as symlinks into .git/hooks/, so updating the scripts in the repo takes effect immediately — no reinstallation needed.

How it works

A headless PTY + alacritty_terminal emulator run behind a background daemon. The MCP server (termin8r) talks to the daemon over a Unix socket, and Claude Code calls the MCP tools via stdio:

flowchart LR
    Agent["Claude Code"] -->|"MCP stdio"| MCP["termin8r<br/>(MCP server)"]
    MCP <-->|"JSON · Unix socket"| Daemon["tu daemon<br/>(session manager)"]
    Daemon <-->|"PTY master fd"| App["Inner app<br/>vim · mc · htop · …"]

Loading

• The daemon auto-starts on first MCP call and auto-exits after 8 hours of inactivity.
• The emulator handles the full xterm command set, including modern shell-integration sequences.

License

MIT

Acknowledgements

This project is a heavily refactored derivative work based on terminal-use by flipbit03.