Documentation

Everything you need to install, configure, and get the most out of ShellAI.

Installation

ShellAI ships as a single self-contained binary. No Node, no Python, no runtime to manage.

Quick install (recommended)

Homebrew (macOS)

Manual download

Download the latest release from GitHub Releases for your platform (macOS Intel/ARM, Linux amd64/arm64, Windows amd64), then move the binary onto your $PATH.

Quick start

After installation, verify it works and make your first request:

On first run, ShellAI auto-detects your API keys from environment variables, or prompts you to configure a provider.

Configuration

ShellAI stores config in ~/.shellai/config.yaml. It's created automatically on first run.

# ~/.shellai/config.yaml
provider: anthropic        # openai | anthropic | gemini | ollama
model: claude-sonnet-4-20250514

# Environment (dev = default, prod = stricter safety)
mode: dev

# Chat settings
chat:
  max_history: 100         # messages per session

# LLM reasoning effort (for supported providers)
llm:
  reasoning_effort: medium # low | medium | high

# Ollama (only needed if provider = ollama)
ollama:
  host: http://localhost:11434
  model: llama3.2

API keys

Keys are stored in your OS keychain — never in the config file. Set them once:

Alternatively, export environment variables — ShellAI picks them up automatically:

export ANTHROPIC_API_KEY=sk-ant-…
export OPENAI_API_KEY=sk-…
export GEMINI_API_KEY=…

Ask

The primary command. Describe what you want in plain English — ShellAI generates the exact shell command, explains it, and shows a safety badge before asking you to confirm.

After generation you'll see an interactive prompt:

Generated: mogrify -quality 80 -format png ./assets/*.png

[WR] Writes files · affects ~34 files

[E]xecute  [C]opy  [M]odify  [R]evise  [Q]uit

Flags

Explain

Paste any command — no matter how cryptic — and get a plain-English breakdown:

ShellAI streams a detailed explanation breaking down each part — flags, pipes, risks, and alternatives.

Fix

Correct the last command you ran, or a command you pass directly:

!! reads from ~/.zsh_history or ~/.bash_history automatically.

Debug

Pipe error output directly to ShellAI for AI analysis and a suggested fix:

Build

Construct complex, multi-part commands from a natural language description:

How do I

Quick one-shot lookup for common tasks. Behaves like ask but optimised for short how-to queries:

Chat mode

A persistent, context-aware AI session that knows your project, git state, and shell history. Think of it as a senior engineer sitting next to you.

Sessions

Sessions are stored as JSON in ~/.shellai/sessions/ with 8-char hex IDs. They're automatically named from your first message and searchable by name or ID prefix.

Slash commands

@file mentions

Type @path/to/file anywhere in a message and ShellAI will attach that file's contents as context (max 100 KB per file).

Keyboard shortcuts

Safety badges

Every generated command is risk-analysed after generation and assigned one or more badges:

Production mode

Set mode: prod in your config to enable stricter safety across all commands. In production mode, every destructive command is elevated to high-risk regardless of the LLM's assessment.

Undo system

Before executing a [WR] or [DG] command, ShellAI snapshots the affected files to ~/.shellai/snapshots/. You can restore them with:

Snapshots are kept for 24 hours with a maximum of 50 entries.

LLM providers

ShellAI supports Anthropic, OpenAI, Gemini, Groq, xAI, OpenRouter, Zhipu, and Ollama. It auto-detects which one to use based on available API keys, in priority order: Anthropic → OpenAI → Gemini → Groq → Ollama.

Anthropic

provider: anthropic
model: claude-sonnet-4-20250514   # default

Available models: claude-sonnet-4-20250514, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229

OpenAI

provider: openai
model: gpt-4o   # default

Available models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo

Google Gemini

provider: gemini
model: gemini-2.5-flash   # default

Available models: gemini-2.5-flash, gemini-2.5-pro, gemini-2.5-flash-lite, gemini-2.0-flash

Ollama (offline)

Run ShellAI 100% offline with any locally available Ollama model:

Auto routing (FrugalRoute)

Set provider: auto to let ShellAI route each request to the best available model automatically — simple tasks run locally on Ollama (free), complex ones escalate to a cloud provider.

provider: auto

On first use, ShellAI auto-starts FrugalRoute via npx frugalroute — npm fetches the package, it starts on localhost:3100, and ShellAI connects. Subsequent requests reuse the running instance (~10s startup on first use only).

To skip the first-run download, install globally:

Add cloud API keys to FrugalRoute's env file at ~/.frugalroute/.env to enable cloud escalation. Without keys, all requests stay on Ollama.

Models & Capabilities

ShellAI supports seven cloud providers and local models via Ollama. Here's which model to use for which task — no guessing required.

Quick picks

Anthropic (Claude)

Best overall quality for complex tasks, agentic chat, and multi-step tool use. The default provider if you have an API key.

shellai config set-key anthropic <your-api-key>
shellai config set llm.provider anthropic

Google Gemini

Strong free tier. gemini-2.5-flash is free and handles most tasks well. Best starting point if you don't want to enter a credit card.

shellai config set-key gemini <your-api-key>
shellai config set llm.provider gemini

*Free within Google's rate limits. See Google AI Studio for current limits.

OpenAI (GPT)

The original. Well-supported, predictable, works well for code and chat. Use if you already have credits.

shellai config set-key openai <your-api-key>
shellai config set llm.provider openai

Groq

Fastest inference of any provider. Models run on custom LPU hardware — responses are near-instant. Trade-off: less capable models than Anthropic/OpenAI.

shellai config set-key groq <your-api-key>
shellai config set llm.provider groq

xAI (Grok)

Strong at reasoning and real-time knowledge. Competitive pricing for complex tasks.

shellai config set-key xai <your-api-key>
shellai config set llm.provider xai

OpenRouter

Access to 100+ models through a single API key — including free models not available directly (DeepSeek, Mistral, Meta Llama). See openrouter.ai/models for the full list.

shellai config set-key openrouter <your-api-key>
shellai config set llm.provider openrouter

Zhipu AI (GLM)

Chinese AI provider. Strong at Chinese language tasks. Competitive pricing.

shellai config set-key zhipu <your-api-key>
shellai config set llm.provider zhipu

Ollama — what fits your GPU

Local models work great for simple ask/fix/explain commands. For complex agentic tasks, models under 32B will struggle — not because of ShellAI, but the models themselves.

Task-based recommendations

Switching models

Or use the in-chat model picker: type /model in chat mode to switch interactively.

Workflows

Pre-built playbooks for common DevOps tasks. Run with one command, no setup required.

Built-in workflows

Macros

Reusable command templates with {{variable}} substitution. Stored in ~/.shellai/macros/.

# Example macro: deploy.json
{
  "name": "deploy",
  "template": "git push {{remote:origin}} {{branch:main}} && ssh {{host}} 'cd {{path}} && ./deploy.sh'",
  "variables": {
    "remote": { "type": "string", "default": "origin" },
    "branch": { "type": "string", "default": "main" },
    "host":   { "type": "string" },
    "path":   { "type": "path" }
  }
}

MCP server setup

ShellAI includes an MCP server that gives Claude Desktop, Cursor, and other AI tools intelligent, safety-aware shell access.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "shellai": {
      "command": "npx",
      "args": ["@shellai/mcp-server"],
      "env": {
        "SHELLAI_API_KEY": "your-api-key"
      }
    }
  }
}

Available MCP tools

Configuration reference

Full annotated ~/.shellai/config.yaml:

provider: anthropic         # openai | anthropic | gemini | ollama
model: ""                  # override default model for provider

mode: dev                  # dev | prod (prod elevates all DG commands)

shell: ""                  # override auto-detected shell

chat:
  max_history: 100         # max messages kept per session

llm:
  reasoning_effort: medium # low | medium | high
  planner_enabled: true    # auto-decompose complex tasks (default: true)
  planner_provider: ""     # provider for decomposition (empty = auto-select cheapest)
  planner_model: ""        # model for decomposition  (empty = auto-select cheapest)

ollama:
  host: http://localhost:11434
  model: llama3.2

nyxcore:
  enabled: true            # auto-discovered on localhost
  host: ""                 # override discovery host
  port: 0                  # override discovery port