ShellSage

Overview

ShellSage works by understanding your terminal context and leveraging powerful language models (Claude or GPT) to provide intelligent assistance for:

• Shell commands and scripting
• System administration tasks
• Git operations
• File management
• Process handling
• Real-time problem solving

What sets ShellSage apart is its ability to:

• Read your terminal context through tmux integration
• Provide responses based on your current terminal state
• Accept piped input for direct analysis
• Target specific tmux panes for focused assistance

Whether you’re a seasoned sysadmin or just getting started with the command line, ShellSage acts as your intelligent terminal companion, ready to help with both simple commands and complex operations.

Installation

Install ShellSage directly from PyPI using pip:

pip install shell_sage

Prerequisites

1. API Key Setup

   # For Claude (default)
   export ANTHROPIC_API_KEY=sk...
   
   # For OpenAI (optional)
   export OPENAI_API_KEY=sk...

2. tmux Configuration

   We recommend using this optimized tmux configuration for the best ShellSage experience. Create or edit your ~/.tmux.conf:

   # Enable mouse support
   set -g mouse on
   
   # Show pane ID and time in status bar
   set -g status-right '#{pane_id} | %H:%M '
   
   # Keep terminal content visible (needed for neovim)
   set-option -g alternate-screen off
   
   # Enable vi mode for better copy/paste
   set-window-option -g mode-keys vi
   
   # Improved search and copy bindings
   bind-key / copy-mode\; send-key ?
   bind-key -T copy-mode-vi y \
     send-key -X start-of-line\; \
     send-key -X begin-selection\; \
     send-key -X end-of-line\; \
     send-key -X cursor-left\; \
     send-key -X copy-selection-and-cancel\; \
     paste-buffer

   Reload tmux config:

   tmux source ~/.tmux.conf

This configuration enables mouse support, displays pane IDs (crucial for targeting specific panes), maintains terminal content visibility, and adds vim-style keybindings for efficient navigation and text selection.

Getting Started

Basic Usage

ShellSage is designed to run within a tmux session. Here are the core commands:

# Basic usage
ssage hi ShellSage

# Pipe content to ShellSage
cat error.log | ssage explain this error

# Target a specific tmux pane
ssage --pid %3 what is happening in this pane?

# Automatically fill in the command to run
ssage --c how can I list all files including the hidden ones?

# Log the model, timestamp, query and response to a local SQLite database
ssage --log "how can i remove the file"

The --pid flag is particularly useful when you want to analyze content from a different pane. The pane ID is visible in your tmux status bar (configured earlier).

The --log option saves log data to an SQLite database located at ~/.shell_sage/log_db/logs.db.

Using Alternative Model Providers

ShellSage supports using different LLM providers through base URL configuration. This allows you to use local models or alternative API endpoints:

# Use a local Ollama endpoint
ssage --provider openai --model llama3.2 --base_url http://localhost:11434/v1 --api_key ollama what is rsync?

# Use together.ai
ssage --provider openai --model mistralai/Mistral-7B-Instruct-v0.3 --base_url https://api.together.xyz/v1 help me with sed # make sure you've set your together API key in your shell_sage conf

This is particularly useful for:

• Running models locally for privacy/offline use
• Using alternative hosting providers
• Testing different model implementations
• Accessing specialized model deployments

You can also set these configurations permanently in your ShellSage config file (~/.config/shell_sage/shell_sage.conf). See next section for details.

Configuration

ShellSage can be customized through its configuration file located at ~/.config/shell_sage/shell_sage.conf. Here’s a complete configuration example:

[DEFAULT]
# Choose your AI model provider
provider = anthropic     # or 'openai'
model = claude-3-5-sonnet-20241022 # or 'gpt-4o-mini' for OpenAI
base_url = # leave empty to use default openai endpoint
api_key = # leave empty to default to using your OPENAI_API_KEY env var

# Terminal history settings
history_lines = -1      # -1 for all history

# Code display preferences
code_theme = monokai    # syntax highlighting theme
code_lexer = python     # default code lexer
log = False      # Set to true to enable logging by default

You can find all of the code theme and code lexer options here: https://pygments.org/styles/

Command Line Overrides

Any configuration option can be overridden via command line arguments:

# Use OpenAI instead of Claude for a single query
ssage --provider openai --model gpt-4o-mini "explain this error"

# Adjust history lines for a specific query
ssage --history-lines 50 "what commands did I just run?"

Developer Setup Guide

Prerequisites

• Python 3.9+
• pip
• nbdev (latest version)
• Quarto (for documentation generation)

Installation

1. Install the development dependencies:

# installing all dependencies
pip install -e '.[dev]'
nbdev_install_quarto

2. Set up the tmux environment for development:

Ubuntu/Debian

sudo apt update
sudo apt install tmux -y

3. Start tmux:

tmux

nbdev Development Workflow

Initialize Project

nbdev_install_quarto

Update README from index.ipynb

nbdev_readme

Export Python Modules from Notebooks

nbdev_export

Advanced Use Cases

Git Workflow Enhancement

# Review changes before commit
git diff | ssage summarize these changes

# Get commit message suggestions
git diff --staged | ssage suggest a commit message

# Analyze PR feedback
gh pr view 123 | ssage summarize this PR feedback

Log Analysis

# Quick error investigation
journalctl -xe | ssage what's causing these errors?

# Apache/Nginx log analysis
tail -n 100 /var/log/nginx/access.log | ssage analyze this traffic pattern

# System performance investigation
top -b -n 1 | ssage explain system resource usage

Docker Management

# Container troubleshooting
docker logs my-container | ssage "what is wrong with this container?"

# Image optimization
docker history my-image | ssage suggest optimization improvements

# Compose file analysis
cat docker-compose.yml | ssage review this compose configuration

Database Operations

# Query optimization
psql -c "EXPLAIN ANALYZE SELECT..." | ssage optimize this query

# Schema review
pg_dump --schema-only mydb | ssage review this database schema

# Index suggestions
psql -c "\di+" | ssage suggest missing indexes

Tips & Best Practices

Effective Usage Patterns

1. Contextual Queries

   • Keep your tmux pane IDs visible in the status bar
   • Use --pid when referencing other panes
   • Let ShellSage see your recent command history for better context

2. Piping Best Practices

   # Pipe logs directly
   tail log.txt | ssage "summarize these logs"
   
   # Combine commands
   git diff | ssage "review these changes"

Getting Help

# View all available options
ssage --help

# Submit issues or feature requests
# https://github.com/AnswerDotAI/shell_sage/issues

Contributing

ShellSage is built using nbdev. For detailed contribution guidelines, please see our CONTRIBUTING.md file.

We welcome contributions of all kinds:

• Bug reports
• Feature requests
• Documentation improvements
• Code contributions

Please visit our GitHub repository to get started.