shell-use
Let agents use the shell like a human.
Open source Open in the app JSON README (API)
About
Let agents use the shell like a human.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- kyuheon-kr
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Forks
- 1
- Last push
- 2026-01-26T03:39:56Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:22
- Updated
- 2026-08-29 04:00:22
- Origin id
io.github.kyuheon-kr/shell-use
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
| Tool | Description |
|------|-------------|
| `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
| Variable | Description | Required |
|----------|-------------|----------|
| `SHELL_USE_SESSIONS` | Comma-separated list of allowed session names | Yes |
| `SHELL_USE_SOCKET` | Path to tmux socket (default: `/tmux/tmux.sock` in Docker) | No |
---
### Acknowledgments
Inspired by [browser-use](https://github.com/browser-use/browser-use).