Skip to main content

ShellMate

Intelligent shell autocomplete with consequence preview.

Version: 3.0.0
Package: shellmate-cli
License: MIT
Python: 3.10+

ShellMate watches what you type and shows inline risk annotations before you press Enter. A background daemon analyzes commands with deterministic rules, an exact-match cache, and a LangGraph pipeline that pulls project context plus Groq / OpenRouter / Grok (xAI) for AI risk and remediation.

How it works

You type in the shell
    → ble.sh (Linux/WSL) or PSReadLine (Windows) adapter
    → IPC to daemon (TCP 127.0.0.1:9823)
    → LangGraph analysis pipeline
    → Inline annotation / confirmation gate
  1. Instant catastrophic check — local YAML rules (rules/catastrophic.yaml), no API.
  2. Debounced partial analysis — after a short pause while typing.
  3. Full analysis — rules → cache → AI + context agents when risk is unclear.

Installation

From PyPI

pip install shellmate-cli

From source

git clone https://github.com/sayan-does/shellmate.git
cd shellmate
pip install -e .

Quick start

1. Prerequisites

Platform Required
Linux / WSL ble.sh (e.g. under ~/.local/share/blesh/ble.sh)
Windows PowerShell with PSReadLine
All At least one of GROQ_API_KEY, OPENROUTER_API_KEY, or XAI_API_KEY

2. Install hooks and configure keys

sm install          # copy adapter → ~/.shellmate/adapters/ and append RC/profile hook
sm config           # select provider (Groq / OpenRouter / Grok xAI), paste API key

Dry-run without changing files:

sm install --dry-run

3. Start the daemon

sm enable

Starts the daemon for the current directory (Watcher, Librarian, and other agents). Check with sm status.

4. Type normally

Inline annotations appear under the line as you type. Catastrophic commands require a second Enter to confirm.

5. Stop / remove

sm disable          # stop daemon
sm uninstall        # remove shell hooks (keeps config)

Autocomplete features

ShellMate’s main UX is in-shell autocomplete annotations (not a separate sm -a command). Adapters hook ble.sh or PSReadLine and talk to the daemon over IPC.

Two-phase typing feedback

Phase Latency What happens
1 — Instant <10ms, no API /instant-check against rules/catastrophic.yaml. Blocking commands get an immediate annotation.
2 — Debounced ~300ms after you pause /analyze-partial runs the analysis pipeline and replaces the annotation in place with risk + badges.
$ git push --force
[!] rewrites history [PROD] BH

$ rm -rf /
[!] BLOCKING - Type again to confirm

Consequence preview (Tab × 2)

  1. First Tab — completion / ghost-text suggestion
  2. Second Tab — accept suggestion and show a consequence preview below the prompt:
  → Force-pushes and rewrites remote history
  → Reversible: No  |  remote: origin/main
  → Safe alt: git push --force-with-lease

On HIGH / CRITICAL / blocking severity, Enter is gated until you confirm again.

Platform Completion surface
Linux / WSL (ble.sh) Tab bound to ShellMate complete widget
PowerShell 7.2+ PSReadLine predictor (powershell_predictor.ps1) when available
PowerShell 5.1 Tab handler ghost-text fallback

Double-Enter confirmation

Dangerous commands do not run on the first Enter:

  1. First Enter → blocked; annotation asks you to confirm
  2. Second Enter (same command) → allowed

Applies to catastrophic instant matches and to HIGH/CRITICAL consequence previews.

Annotation badges

Short inline text under the command (ASCII-safe on all platforms):

Kind Examples
Risk [OK] [i] [!] [!!] [X]
Environment [PROD] [STAGE] [DEV] [CI]
Time BH (business hours) · AH (after hours)
Chain / consequence [BROKEN] [ESCALATION] [IRREVERSIBLE]

Bracket syntax

Typed as part of the command line; adapters/daemon strip and honor them:

Syntax Purpose Example
[?…] Ask a question about the command docker rm $(docker ps -aq) [?why dangerous]
[!…] Directive to the analyzer rm -rf /tmp [!force]
[@key=value] Override context (e.g. environment) git reset --hard [@env=production]

Surfaces

Adapter Shell Role
ble_adapter.sh bash/zsh + ble.sh Primary Linux/WSL autocomplete
powershell_adapter.ps1 PowerShell + PSReadLine Primary Windows autocomplete
powershell_predictor.ps1 PowerShell 7.2+ Optional ghost-text predictor
bash_adapter.sh / zsh_adapter.zsh — Deprecated stubs

Requires at least one of GROQ_API_KEY, OPENROUTER_API_KEY, or XAI_API_KEY for AI annotations and consequence previews. Instant catastrophic checks still use local rules.

CLI

Command Description
sm install Install shell hooks (bash/zsh → ble adapter, PowerShell → PS adapter)
sm uninstall Remove shell hooks
sm config Configure API keys and settings
sm enable Start daemon (autocomplete mode)
sm disable Stop daemon and clean session
sm status Daemon, agents, providers, credentials
sm --help Help
sm --version Version
sm --no-color <cmd> Plain text output

sm config usages

sm config                        # validate existing keys; select provider → paste key
sm config --show                 # masked credentials
sm config provider risk_analysis xai grok-3-mini   # set provider role
sm config cache.max_entries 200  # YAML override (dotted key)

Interactive setup asks you to pick Groq, OpenRouter, or Grok (xAI), then paste the key. Existing keys are checked against the provider API.

Exit codes

Code Meaning
0 Success
2 Usage error
3 Temporary error (e.g. interrupt)
4 Internal error

Shell adapters

See Autocomplete features for behavior. sm install copies the ble or PowerShell adapter into ~/.shellmate/adapters/ and appends a source line to your RC / profile.

Architecture

Analysis pipeline

Defined in shellmate/orchestration/analysis_graph.py (LangGraph StateGraph):

flowchart TD
    START([start]) --> sanitize --> parse --> command_chain --> rules --> cache
    cache -->|early exit| format
    cache -->|needs AI| supervisor
    supervisor -->|gather context| context_worker
    supervisor -->|env only| env_context
    context_worker --> risk_analyzer
    env_context --> risk_analyzer
    risk_analyzer --> consequence_builder --> remediation --> command_guide --> format
    format --> query
    query --> END([end])
Node Role
sanitize / parse Typo / syntax checks; tokenize
command_chain Multi-step / chain pattern detection
rules YAML rules under shellmate/rules/definitions/
cache Exact-match in-memory cache (no FAISS)
supervisor Groq (or heuristic) decides context needs
context_worker / env_context Parallel agent queries or env-only path
risk_analyzer Groq risk assessment
consequence_builder Structured consequence preview
remediation OpenRouter safer alternatives
command_guide Groq “what you meant” guide
format / query Final payload; optional [?…] query handling

Early exits (skip AI): sanitizer correction, high-confidence rule match, cache hit.

Agents (daemon)

Started with sm enable:

Agent Purpose
Watcher OS, shell, git, tech-stack snapshot
Librarian Project file index + search
Environment Environment / staging signals
CommandChain Chain-pattern analysis
Query Answers [?…] queries

Repomix-style pack search runs alongside Librarian in the context worker when needed.

Providers

Stage Default Fallback
Supervisor / risk / guide Groq Grok (xAI) / heuristic
Remediation OpenRouter Grok (xAI) / Groq guide / generic text

Configure at least one of Groq, OpenRouter, or Grok (xAI). Groq covers risk analysis, supervisor routing, and command guide; OpenRouter covers remediation; xAI can cover both risk and remediation. Instant catastrophic gating still uses local rules either way.

Configuration

Directories

Purpose Linux / macOS Windows
Config + .env ~/.config/shellmate %APPDATA%\ShellMate
State / sessions / logs ~/.local/state/shellmate %LOCALAPPDATA%\ShellMate
Cache dir ~/.cache/shellmate %LOCALAPPDATA%\ShellMate\cache
Installed adapters ~/.shellmate/adapters/ %USERPROFILE%\.shellmate\adapters\

Credentials file: <config_dir>/.env (permissions restricted on Unix).

Environment variables

Variable Required Purpose
GROQ_API_KEY At least one of Groq / OpenRouter / xAI Risk analysis, supervisor, command guide
OPENROUTER_API_KEY At least one of Groq / OpenRouter / xAI Remediation alternatives
XAI_API_KEY At least one of Groq / OpenRouter / xAI Risk analysis and remediation via Grok
CONTEXT7_API_KEY No Optional docs lookup
GROQ_SUPERVISOR_MODEL No Override supervisor model (default qwen/qwen3.8-27b)
XAI_MODEL No Override Grok model (default grok-3-mini)

Optional YAML overrides live in <config_dir>/config.yaml.

Requirements

  • Python 3.10+
  • ble.sh (Linux/WSL) or PowerShell + PSReadLine (Windows)
  • At least one of GROQ_API_KEY, OPENROUTER_API_KEY, or XAI_API_KEY (Groq + OpenRouter recommended for full risk + remediation)

Dependencies (authoritative: pyproject.toml)

  • click, rich, pyyaml — CLI / UI
  • langgraph, langchain-core — orchestration
  • groq, openai, aiohttp — providers
  • psutil, watchdog — runtime monitoring
  • numpy — declared runtime dependency

Development

git clone https://github.com/sayan-does/shellmate.git
cd shellmate
pip install -e ".[dev]"
python -m build

CI builds and smoke-tests the wheel on Python 3.10–3.12. Publishing runs on v* tags via Trusted Publishing (.github/workflows/publish.yml).

License

MIT

Metadata

Release files for shellmate-cli 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for shellmate-cli 3.0.0
File Size Uploaded Provenance Actions
shellmate_cli-3.0.0.tar.gz 119.4 kB With provenance Details for shellmate_cli-3.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for shellmate-cli 3.0.0
File Interpreter ABI Platform Actions
shellmate_cli-3.0.0-py3-none-any.whl Python 3 none any Details for shellmate_cli-3.0.0-py3-none-any.whl

Total release size: 269.8 kB

Release files / shellmate_cli-3.0.0.tar.gz

Download URL shellmate_cli-3.0.0.tar.gz
Size 119.4 kB
Tags Source
SHA-256 checksum
How to use checksums
9ce32c192cc6efe3d372f8b63387c52c7b4bc44bd15a5aa98ebac0b92cee9594
BLAKE2b-256 checksum
How to use checksums
5f68f69a9db442c98837c887a5e1c1ee8c2e7c4eb9a3ee6bfd59f229398b49de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / shellmate_cli-3.0.0-py3-none-any.whl

Download URL shellmate_cli-3.0.0-py3-none-any.whl
Size 150.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9f958201d9d50211c00fd208602a0439abbd3ee30d2d55b8b901977d787b4d50
BLAKE2b-256 checksum
How to use checksums
7a1a1aca1eee09e92862466bf8a00efe3866dc0cefc7e0b0083f36667a6c5bb4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for shellmate-cli 3.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for shellmate_cli-3.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page