shell-use

io.github.kyuheon-krPublished by GitHub account kyuheon-krv1.0.0Updated Oct 27, 2026

Let agents use the shell like a human.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

Lets an AI assistant drive tmux terminal sessions like a human: capture screen text, send keystrokes and text, and scroll history.

What you can do
  • List the allowed tmux sessions the assistant may attach to
  • Capture the current terminal screen text, optionally scrolling back
  • Send key input such as Enter, Ctrl+C or arrow keys
  • Send literal text, optionally followed by Enter
  • Scroll through terminal history and exit copy-mode
  • Interact with any CLI application running in the session, such as vim, htop or gdb
When to use it
Useful when an assistant needs to operate interactive terminal programs that a plain command runner cannot handle, or when you want it to watch and steer a long-running tmux session on your machine.
Requirements
Runs as a local Docker container (image ghcr.io/kyuheon-kr/shell-use) over stdio, so Docker is needed. A tmux session must already exist, and its socket path is mounted into the container. SHELL_USE_SESSIONS is required; SHELL_USE_SOCKET is optional and defaults to /tmux/tmux.sock in Docker. Desktop client only.
Before you install
The assistant can type into your live terminal sessions, so anything sent runs as your user in those shells, including destructive commands or interactive prompts. Only the sessions named in SHELL_USE_SESSIONS are exposed, so keep that list narrow. Mounting the tmux socket gives the container control of those sessions.

Installation

In SourceWeft

  1. Open shell-use in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

shell-use

Let agents use the shell like a human.

Features

  • Interact with any CLI application (vim, htop, gdb, etc.)
  • Send special keys (Ctrl+C, Enter, arrow keys, etc.)
  • Dockerized for easy deployment

Available Tools

ToolDescription
list_sessions()Returns allowed session names
capture(session, scroll_back?)Captures terminal screen text
send_keys(session, keys)Sends key input (e.g., Enter, C-c)
send_text(session, text, enter?)Sends literal text (enter=True to press Enter)
scroll(session, direction, amount?)Scrolls through history
exit_scroll_mode(session)Exits copy-mode

Setup

1. Build the Docker image
bash
docker build -t shell-use:latest .
2. Create a tmux session
bash
tmux new-session -s dev
2.1. Get the tmux socket path
bash
SOCK="$(tmux display-message -p -F '#{socket_path}')"[ -S "$SOCK" ] || { echo "tmux socket not found: $SOCK"; exit 1; }
3. Configure your MCP client

Claude Code:

bash
claude mcp add shell-use \  -- docker run -i --rm \  -v "$SOCK":/tmux/tmux.sock \  -e SHELL_USE_SOCKET=/tmux/tmux.sock \  -e SHELL_USE_SESSIONS=dev \  shell-use:latest

Claude Desktop (claude_desktop_config.json):

json
{  "mcpServers": {    "shell-use": {      "command": "docker",      "args": [        "run", "-i", "--rm",        "-v", "/tmp/tmux-1000/default:/tmux/tmux.sock",        "-e", "SHELL_USE_SOCKET=/tmux/tmux.sock",        "-e", "SHELL_USE_SESSIONS=dev",        "shell-use:latest"      ]    }  }}

Replace /tmp/tmux-1000/default with the path from tmux display-message -p -F '#{socket_path}'.

Environment Variables

VariableDescriptionRequired
SHELL_USE_SESSIONSComma-separated list of allowed session namesYes
SHELL_USE_SOCKETPath to tmux socket (default: /tmux/tmux.sock in Docker)No

Acknowledgments

Inspired by browser-use.

Source: README.md at commit 5fe5fa8

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts