Documentation

Everything you need to set up, pair, and run ShellMate.

# Installation

Install ShellMate globally using npm. This gives you the shellmate command.

$ npm install -g shellmate

Verify the installation:

$ shellmate --version

Prerequisites: Node.js 18+ and npm. For self-hosting the control plane, you'll also need Go 1.23+.

# Device Pairing

Pairing connects your mobile device to your desktop machine through a secure encrypted key exchange. Once paired, you can control your dev sessions from your phone.

Interactive pairing

The simplest way to pair. This launches a TUI experience that walks you through the process:

$ shellmate pair

A QR code will appear in your terminal. Open the ShellMate mobile app and scan it to complete pairing.

Pairing with a link

If you prefer to pair using a deep link instead of the TUI:

$ shellmate pair-link --control-plane-url https://your-server.com --pairing-code ABC123

Add --qr to print the link as a scannable QR code.

Unpairing

Remove the pairing state from your machine:

$ shellmate unpair

How it works: ShellMate uses a rendezvous server to facilitate the initial key exchange between your devices. Once paired, a shared encrypted channel is established. The rendezvous server is only involved during pairing — after that, communication goes directly through the control plane.

# Your First Session

After installing and pairing, you can start an AI session with a single command. ShellMate will automatically start the daemon if it isn't running.

$ shellmate claude "help me set up a new project"

This will:

  1. Ensure the daemon is running
  2. Check your pairing state
  3. Create (or resume) a session with the Claude provider
  4. Attach your terminal to an interactive stream

You can also launch the interactive TUI without specifying a provider by just running shellmate on its own.

# The Daemon

The daemon is a persistent background process that manages sessions, relays streams between your devices, and maintains heartbeat connections to the control plane.

Starting

Start the daemon in the background:

$ shellmate daemon start

Or run it in the foreground (useful for debugging):

$ shellmate daemon start-sync

Checking status

$ shellmate daemon status

Stopping

$ shellmate daemon stop

Note: You don't have to start the daemon manually. When you launch a session (e.g. shellmate claude), ShellMate automatically ensures the daemon is running.

# AI Providers

ShellMate supports multiple AI providers as first-class shortcuts. Each shortcut maps to a pre-configured provider profile.

Command Provider
shellmate claude Claude (Anthropic)
shellmate codex Codex (OpenAI)
shellmate gemini Gemini (Google)
shellmate opencode OpenCode

Pass a message directly or start an interactive session:

# Interactive session
$ shellmate claude
# With a prompt
$ shellmate codex "optimize this function"
# Force a new session
$ shellmate gemini --new "start fresh"

# Sessions

Sessions are persistent AI conversations. By default, ShellMate resumes your last session with a provider. You can override this behavior:

# Resume last session (default)
$ shellmate claude --resume
# Start a new session
$ shellmate claude --new
# Give it a title
$ shellmate claude --new --title "refactor auth module"
# Start detached (daemon-only, no terminal)
$ shellmate claude --detach

# MCP Servers

ShellMate can install Model Context Protocol servers that let AI tools interact with your machine through a standardized interface.

Check status

See which MCP servers are installed for each client:

$ shellmate mcp status

Install

Install MCP servers for all supported clients:

$ shellmate mcp install --all

Or install for specific clients only:

$ shellmate mcp install --clients claude,codex

# Self-Hosting

ShellMate is designed to be self-hosted. The open-source core includes the local daemon and control-plane service — everything you need for a single-user setup.

1. Start the control plane

The control plane is the API + relay + state service that coordinates sessions:

$ cd services/control-plane
$ go run ./cmd/server

By default it listens on http://127.0.0.1:8080.

2. Start the daemon

In a separate terminal:

$ cd apps/daemon-go
$ go run ./cmd/daemon

3. Persistence options

The control plane supports multiple persistence backends:

  • •In-memory (default) — no configuration needed, state is lost on restart
  • •File snapshot — set SHELLMATE_STATE_FILE
  • •Turso — set SHELLMATE_TURSO_DATABASE_URL and SHELLMATE_TURSO_AUTH_TOKEN

# Diagnostics

ShellMate includes built-in health checks to troubleshoot your setup.

Quick status

$ shellmate status

Shows whether you're paired and whether the daemon is running.

Full health check

$ shellmate doctor

This validates:

  • • CLI version
  • • Pairing state
  • • Daemon health
  • • Control plane connectivity

Add --strict to treat warnings as failures.

# Environment Variables

These environment variables configure the daemon and control plane connection.

Variable Description
SHELLMATE_CONTROL_PLANE_URL Control plane endpoint (default: http://127.0.0.1:8080)
SHELLMATE_CONTROL_PLANE_TOKEN Auth token for control plane
SHELLMATE_MACHINE_ID Unique device identifier
SHELLMATE_MACHINE_NAME Human-readable machine name
SHELLMATE_DAEMON_LOG_LEVEL Daemon log level (default: info)
SHELLMATE_STATE_FILE Path for file-based persistence
SHELLMATE_TURSO_DATABASE_URL Turso database URL for persistence
SHELLMATE_TURSO_AUTH_TOKEN Turso auth token

Made with love by the Smart AIPI team · GitHub