terminal-use
Lets AI agents drive a real terminal with typing, key presses, clicks and screenshots
- Pricing
- Open source
- Platforms
- CLI, macOS, Linux
- Runs
- Locally
- Version
- 0.2.1
- Listing updated
- 1 day ago
About terminal-use
terminal-use is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
Most agent shell tools run a command and return its output, which fails for anything interactive. This server instead runs sessions on a real pseudo-terminal with a terminal emulator, so programs like vim, htop, REPLs, installers and SSH prompts behave as they do for a person. The agent can read the screen as text or render it as a PNG.
Sessions can be an interactive shell or a single command, in which case the exit status is reported and the final screen stays readable. That makes it suitable for testing a CLI or TUI. Waiting is built in, so the agent can block until a command finishes, a regex appears or output goes quiet. You can also attach your own terminal to a session and type alongside the agent, similar to a shared tmux session.
It needs Node.js 22.12 or newer and runs on macOS, Linux or Windows. A Dockerfile is provided for boxing the agent in, and an optional Agent Skill gives recipes for vim, pagers, REPLs and ssh prompts.
Install
Run in a terminal
claude mcp add terminal-use -- npx -y terminal-useAdd to claude_desktop_config.json
{
"mcpServers": {
"terminal-use": {
"command": "npx",
"args": [
"-y",
"terminal-use"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"terminal-use": {
"command": "npx",
"args": [
"-y",
"terminal-use"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"terminal-use": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"terminal-use"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"terminal-use": {
"command": "npx",
"args": [
"-y",
"terminal-use"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"terminal-use": {
"command": "npx",
"args": [
"-y",
"terminal-use"
]
}
}
}Tools this server provides (13)
Taken from the project documentation; the running server may differ.
- terminal_create
- Starts a session as an interactive shell or running one program.
- terminal_list
- Lists sessions.
- terminal_destroy
- Ends a session.
- terminal_type
- Types text, with optional paste.
- terminal_press
- Presses a key or combination.
- terminal_wait
- Waits for a command to finish, a regex or quiet output.
- terminal_read
- Reads the screen or scrollback as text.
- terminal_screenshot
- Renders the screen as a PNG.
- terminal_click
- Left-clicks a cell with a preview step.
- terminal_scroll
- Turns the mouse wheel over a cell.
- terminal_batch
- Sends several inputs in one call.
- terminal_resize
- Changes the terminal size.
- terminal_reset
- Clears the screen or restarts the shell.
What it does
- Real PTY and emulator
- Interprets colours, cursor movement and the alternate screen.
- Text and screenshots
- Read the screen as plain text or as a PNG.
- Smart waiting
- Wait for command exit, matching text or quiet output.
- Watch along
- Attach your own terminal to a session and type with the agent.
- Docker isolation
- Run in a container so the agent sees only mounted files.
- Bundled skill
- An optional Agent Skill with recipes for common interactive programs.
Good for
- Let an agent edit a file in vim
- Test a CLI or TUI end to end
- Drive an installer that asks questions
- Walk through an interactive git rebase
Pricing
Open source
Open-source npm package; no pricing listed.
terminal-use FAQ
What are the requirements?
Node.js 22.12 or newer, on macOS, Linux or Windows.
How do I add it to Claude Code?
Run claude mcp add terminal-use --scope user -- npx -y terminal-use.
Why does it say command not found?
The server may have inherited a bare environment; enable the login shell with the --login flag or login: true.
Can I contain what the agent can reach?
Yes, the Docker setup limits it to what you mount.
Is terminal-use free?
Yes. terminal-use is open source, so you can use and self-host it for free.
How do I add terminal-use to Claude Code?
Run this command in your terminal: claude mcp add terminal-use -- npx -y terminal-use
What are the best alternatives to terminal-use?
The closest alternatives to terminal-use are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to terminal-use

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools