shelli

shelli

Shell Interface — Persistent shell sessions for AI agents

Enables persistent interactive shell sessions (REPLs, SSH, database CLIs, etc.) that survive across CLI invocations.

Installation

Homebrew (macOS/Linux)

brew install schovi/tap/shelli

Go

go install github.com/schovi/shelli@latest

From Source

git clone https://github.com/schovi/shelli
cd shelli
make build

Claude Code Integration

shelli integrates with Claude Code as a plugin (teaches Claude when and how to use shelli) that bundles the MCP server (native tool integration). Installing the plugin sets up both at once.

The shelli binary must be installed and on your PATH first (see Installation). The plugin's MCP server runs shelli daemon --mcp.

Install via Marketplace (recommended)

This repo is a Claude Code plugin marketplace. Add it and install the plugin:

claude plugin marketplace add schovi/shelli
claude plugin install shelli@shelli

That single plugin installs:

• Skills: when/how to use persistent sessions (core, auto-detector, TUI testing)
• /shelli command: explicit entry point for forcing shelli usage
• MCP server shelli: native tool integration (started as shelli daemon --mcp)

To share with a team, commit the marketplace and enable the plugin in your project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "shelli": {
      "source": { "source": "github", "repo": "schovi/shelli" }
    }
  },
  "enabledPlugins": {
    "shelli@shelli": true
  }
}

MCP Server Only (manual)

If you only want the MCP tools without the plugin, add the server to ~/.claude/settings.json:

{
  "mcpServers": {
    "shelli": {
      "command": "shelli",
      "args": ["daemon", "--mcp"]
    }
  }
}

The server exposes these MCP tools to Claude:

• shelli/create - Create a new session
• shelli/exec - Send input and wait for output (primary tool)
• shelli/send - Send input without waiting
• shelli/read - Read session output
• shelli/search - Search output buffer with regex
• shelli/list - List all sessions
• shelli/info - Get detailed session info
• shelli/clear - Clear output buffer
• shelli/resize - Change terminal dimensions
• shelli/stop - Stop session, keep output accessible
• shelli/kill - Stop and delete session

With the plugin installed, Claude will:

1. Automatically detect when persistent sessions are needed
2. Use MCP tools for structured interaction
3. Handle session lifecycle (create, use, cleanup)

Example Interaction

User: "SSH to server.example.com and check disk usage"

Claude: [creates SSH session via MCP, waits for prompt, runs df -h]

User: "Start Python and help me explore this CSV"

Claude: [creates python3 session, imports pandas, loads file interactively]

Commands

create

Create a new interactive session.

shelli create <name> [flags]

Flags:

• --cmd "command" - Command to run (default: $SHELL)
• --env KEY=VALUE - Set environment variable (repeatable)
• --cwd /path - Set working directory
• --cols N - Terminal columns (default: 80)
• --rows N - Terminal rows (default: 24)
• --tui - Enable TUI mode (auto-truncate buffer on frame boundaries)
• --json - Output as JSON

Examples:

shelli create myshell                        # default shell
shelli create pyrepl --cmd "python3"         # Python REPL
shelli create db --cmd "psql -d mydb"        # PostgreSQL
shelli create server --cmd "ssh user@host"   # SSH session
shelli create dev --env "DEBUG=1" --cwd /app # with env and cwd
shelli create wide --cols 200 --rows 50      # large terminal
shelli create vim --cmd "vim" --tui          # TUI mode for editors

exec

Send a command and wait for result. The primary command for AI agents.

shelli exec <name> <input> [flags]

Input is sent as literal text with a newline appended. Escape sequences like \n are NOT interpreted by shelli - they're passed to the shell as-is (the shell may interpret them, e.g., echo -e).

For precise control over escape sequences or TUI apps, use send instead.