ShellMate
A friendly safety net for your terminal.
The terminal is powerful — and a little scary when you're starting out. One wrong command can delete files, wipe a branch, or break something you didn't mean to touch.
ShellMate is like having an experienced friend looking over your shoulder. As you type, it quietly checks your command and, before you press Enter, tells you in plain English what it will do, whether it's risky, and if there's a safer way. It never runs anything for you — you're always the one in control.
$ rm -rf /
[!!] BLOCKING — this would erase everything. Press Enter again only if you're sure.
$ git push --force
→ This rewrites history on the remote branch (others may lose work).
→ Reversible: No | target: origin/main
→ Safer option: git push --force-with-lease
Why you'll like it
- Stops the scary stuff. Genuinely dangerous commands (like
rm -rf /) are caught instantly and ask you to confirm before they run. - Explains commands in plain English. No more guessing what a command does — ShellMate tells you what will happen and whether you can undo it.
- Suggests safer alternatives. When there's a gentler way to do the same thing, it offers it.
- Autocomplete that helps you learn. Press Tab for suggestions as you type.
- Stays out of your way. Safe commands run normally — no pop-ups, no nagging.
- You stay in control. ShellMate only shows you things. It never executes commands on its own.
Get started in 3 steps
1. Install it
pip install shellmate-cli
2. Give it a brain (a free API key)
ShellMate uses an AI service to explain commands. The easiest free option is Groq:
-
Grab a free key at console.groq.com (takes a minute).
-
Tell ShellMate about it:
sm configIt'll ask you to pick a provider and paste your key. That's it — the key is stored privately on your computer, not in your command history.
3. Turn it on
sm install # connects ShellMate to your shell (one time)
sm enable # starts the helper in the background
Now just use your terminal normally. Little notes will appear under your commands as you type.
What you need: Python 3.10+, and either Windows PowerShell or, on Linux/WSL, ble.sh. ShellMate sets up the rest for you.
What it feels like to use
As you type, ShellMate shows a tiny note under your command:
| You type | You see | What it means |
|---|---|---|
ls |
(nothing) | Totally safe — ShellMate stays quiet. |
git push --force |
[!] rewrites history [PROD] |
Heads up: this is risky and you're on production. |
rm -rf / |
[!!] BLOCKING — Enter again to confirm |
Dangerous. It won't run until you really mean it. |
Dangerous commands don't run on the first Enter. You'll get a clear warning, and only a second Enter actually runs them — a gentle "are you sure?" that has saved many people from a bad day.
Want to understand a command? Press Tab for a suggestion, and a short "here's what this will do" preview appears before you commit to it.
Everyday commands
These are the only commands you need day to day:
| Command | What it does |
|---|---|
sm enable |
Turn ShellMate on. |
sm disable |
Turn it off. |
sm status |
Check if it's running and healthy. |
sm config |
Set or update your API key. |
sm uninstall |
Remove ShellMate from your shell (keeps your settings). |
sm --help |
See everything. |
A note on your privacy
Being honest about how it works:
- The instant danger checks (like catching
rm -rf /) run entirely on your computer — no internet needed. - When ShellMate needs AI help to explain a trickier command, the command text you typed is sent to the AI provider you chose (e.g. Groq) so it can analyze it.
- Your API key is stored locally in a private config file, never in your shell history.
- As with any tool that talks to a cloud service, avoid typing passwords or secret keys directly on the command line.
Troubleshooting
- "I don't see any notes." Run
sm statusto confirm the daemon is running, and make sure you ransm enable. On a brand-new install, open a fresh terminal so the shell hook loads. - "It says my AI model isn't available." Some free accounts can't use every model.
ShellMate will warn you at startup and
sm statuslists the models your key can use — set one withsm config. - "Is it slowing me down?" Safe commands get an instant local check (under 10ms). Only genuinely unclear commands ever wait on the AI.
Under the hood (for the curious / power users)
How it works
You type in the shell
→ ble.sh (Linux/WSL) or PSReadLine (Windows) adapter
→ IPC to a background daemon (TCP 127.0.0.1:9823)
→ LangGraph analysis pipeline
→ Inline annotation / confirmation gate
Three tiers, fastest first:
- Instant catastrophic check — local YAML rules (
shellmate/rules/catastrophic.yaml), no API, <10ms. - Debounced partial analysis — ~300ms after you pause typing (
/analyze-partial). - Full analysis — rules → exact-match cache → AI + context agents when risk is unclear.
Install from source
git clone https://github.com/sayan-does/shellmate.git
cd shellmate
pip install -e ".[dev]"
python -m build
Annotation badges
| 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 inline; adapters 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 | git reset --hard [@env=production] |
Full CLI
| Command | Description |
|---|---|
sm install |
Install shell hooks (bash/zsh → ble adapter, PowerShell → PS adapter) |
sm uninstall |
Remove shell hooks (keeps config) |
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 / sm --version |
Help / version |
sm --no-color <cmd> |
Plain-text output |
sm install --dry-run # preview changes without touching files
sm config --show # masked credentials
sm config provider risk_analysis xai grok-3-mini # set a provider role
sm config cache.max_entries 200 # YAML override (dotted key)
Exit codes: 0 success · 2 usage error · 3 temporary error · 4 internal error.
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])
Early exits (skip AI): sanitizer correction, high-confidence rule match, cache hit.
Daemon agents (started by 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 |
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). Instant catastrophic gating always uses local rules, with or without a key.
Where things live
| Purpose | Linux / macOS | Windows |
|---|---|---|
Config + .env |
~/.config/shellmate |
%APPDATA%\ShellMate |
| State / sessions / logs | ~/.local/state/shellmate |
%LOCALAPPDATA%\ShellMate |
| Cache | ~/.cache/shellmate |
%LOCALAPPDATA%\ShellMate\cache |
| Installed adapters | ~/.shellmate/adapters/ |
%USERPROFILE%\.shellmate\adapters\ |
Environment variables
| Variable | Required | Purpose |
|---|---|---|
GROQ_API_KEY |
one of the three | Risk analysis, supervisor, command guide |
OPENROUTER_API_KEY |
one of the three | Remediation alternatives |
XAI_API_KEY |
one of the three | Risk + 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.
Dependencies (authoritative: pyproject.toml)
click, rich, pyyaml (CLI/UI) · langgraph, langchain-core (orchestration) ·
groq, openai, aiohttp (providers) · psutil, watchdog (runtime) · numpy.
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).
Made to make the terminal a little less scary. MIT licensed — contributions welcome at github.com/sayan-does/shellmate.
Metadata
Release files for shellmate-cli 3.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shellmate_cli-3.0.2.tar.gz | 122.7 kB | With provenance | Details for shellmate_cli-3.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shellmate_cli-3.0.2-py3-none-any.whl | Python 3 | none | any | Details for shellmate_cli-3.0.2-py3-none-any.whl |
Total release size: 275.4 kB
Release files / shellmate_cli-3.0.2.tar.gz
| Download URL | shellmate_cli-3.0.2.tar.gz |
|---|---|
| Size | 122.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6bb2fff2f66de1fbd86bbb20f820029281ba6021efa215ee6429fb887eb0c0ec
|
|
BLAKE2b-256 checksum How to use checksums |
bc41df98d16f87f898cc0579ecac58771ca551dfca1c5ee22c7c15318414ea51
|
| 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 logRelease files / shellmate_cli-3.0.2-py3-none-any.whl
| Download URL | shellmate_cli-3.0.2-py3-none-any.whl |
|---|---|
| Size | 152.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
acef527fc3dad3c4b04f6e7e509d9c987f51d47ba68efa8dcf1ee02f5f438d04
|
|
BLAKE2b-256 checksum How to use checksums |
9b1d677812a4836ec4772f89c8a49048688e7c56c6f1215bcc9fceaf8d6f3d02
|
| 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 logSecurity for shellmate-cli 3.0.2
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.
Attestation for shellmate_cli-3.0.2.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 logA 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.