Repolode
Submit
AnswerDotAI

AnswerDotAI/shell_sage

AI command-line assistant that reads your tmux terminal history and piped output to help with shell commands and scripts.

View on GitHubWebsite
Stars
407
Forks
44
Open issues
21
Last commit
11 days ago

What is it?

ShellSage is an AI assistant for the terminal, invoked with the `ssage` command. It runs inside a tmux workflow: it reads your current pane's history, or the histories of several panes, to understand what you ran and what went wrong, then answers with explanations, corrected commands and examples. You can also pipe command output or file contents straight into it for analysis.

It supports several LLM providers, including Claude, OpenAI GPT, Gemini, DeepSeek and OpenRouter, as well as local or OpenAI-compatible endpoints through Ollama-style base URLs. An optional bash tool, built on the safecmd allow-list library, lets the assistant run commands on your behalf, and it can also view files, search code and make edits with your permission. Interactions can be logged to SQLite, and suggested code blocks can be inserted into your prompt with a keyboard shortcut.

Key features

  • 01Reads tmux pane history to give context-aware answers about recent commands and errors.
  • 02Accepts piped command output or file contents for analysis.
  • 03Supports multiple LLM providers, including Claude, GPT, Gemini and OpenAI-compatible APIs.
  • 04Optional bash tool with an allow-list safety layer for running commands.
  • 05Can view, search and edit files with user permission.
  • 06Logs interactions to SQLite and inserts suggested code blocks into the prompt.

Use cases

  • Diagnosing why a shell command or find expression failed, using the terminal history as context.
  • Explaining error logs from journalctl or other command output piped into the tool.
  • Learning unfamiliar commands, flags and git workflows from the terminal.
  • Asking an assistant to inspect files or run safe commands while staying in the terminal.

Quick start

  1. 1

    Install ShellSage from PyPI with pip

    pip install shell-sage
  2. 2

    Set your LLM API key (Claude is the default)

    export ANTHROPIC_API_KEY=sk...
  3. 3

    Run a test greeting to confirm the setup works

    ssage hi

Things to know

  • Requires an API key from a paid LLM provider such as Anthropic or OpenAI.
  • Works best inside tmux, and full terminal context depends on a tmux setup.
  • The README badge says MIT while the repository metadata says Apache-2.0, so check the LICENSE file.

In collections

CLI & terminal tools

Topics

#ai#shell#terminal#tmux#llm#cli#sysadmin#bash

FAQ

What is shell_sage?
AI command-line assistant that reads your tmux terminal history and piped output to help with shell commands and scripts. ShellSage is an AI assistant for the terminal, invoked with the `ssage` command. It runs inside a tmux workflow: it reads your current pane's history, or the histories of several panes, to understand what you ran and what went wrong, then answers with explanations, corrected commands and examples. You can also pipe command output or file contents straight into it for analysis.
Is shell_sage free to use? What license does it have?
shell_sage is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is shell_sage still maintained?
Actively maintained. The last commit to shell_sage was on Oct 28, 2026.
What can I use shell_sage for?
Diagnosing why a shell command or find expression failed, using the terminal history as context. Explaining error logs from journalctl or other command output piped into the tool. Learning unfamiliar commands, flags and git workflows from the terminal. Asking an assistant to inspect files or run safe commands while staying in the terminal.
How do I install shell_sage?
Install ShellSage from PyPI with pip: pip install shell-sage Set your LLM API key (Claude is the default): export ANTHROPIC_API_KEY=sk... Run a test greeting to confirm the setup works: ssage hi
Where can I get shell_sage?
The source code and installation instructions are on GitHub: https://github.com/AnswerDotAI/shell_sage

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects