Metadata-Version: 2.4
Name: shell-sage
Version: 0.1.1
Summary: Your favorite AI buddy right in your terminal
Home-page: https://github.com/AnswerDotAI/shell_sage
Author: ncoop57
Author-email: nc@answer.ai
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: claudette
Requires-Dist: cosette
Requires-Dist: fastcore>=1.7.29
Requires-Dist: fastlite
Requires-Dist: msglm
Requires-Dist: rich
Provides-Extra: dev
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ShellSage


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## 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:

``` sh
pip install shell-sage
```

### Prerequisites

1.  **API Key Setup**

    ``` sh
    # 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`:

    ``` sh
    # 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:

    ``` sh
    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:

``` sh
# 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:

``` sh
# 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:

``` ini
[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:

``` sh
# 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?"
```

### Advanced Use Cases

#### Git Workflow Enhancement

``` sh
# 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

``` sh
# 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

``` sh
# 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

``` sh
# 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**

    ``` sh
    # Pipe logs directly
    tail log.txt | ssage "summarize these logs"

    # Combine commands
    git diff | ssage "review these changes"
    ```

### Getting Help

``` sh
# View all available options
ssage --help

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

## Contributing

ShellSage is built using [nbdev](https://nbdev.fast.ai/). For detailed
contribution guidelines, please see our
[CONTRIBUTING.md](CONTRIBUTING.md) file.

We welcome contributions of all kinds:

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

Please visit our [GitHub
repository](https://github.com/AnswerDotAI/shell_sage) to get started.
