shell-sage


Nameshell-sage JSON
Version 0.0.7 PyPI version JSON
download
home_pagehttps://github.com/AnswerDotAI/shell_sage
SummaryYour favorite AI buddy right in your terminal
upload_time2025-02-01 15:09:17
maintainerNone
docs_urlNone
authorncoop57
requires_python>=3.10
licenseApache Software License 2.0
keywords nbdev jupyter notebook python
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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?
```

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).

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

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

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

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/AnswerDotAI/shell_sage",
    "name": "shell-sage",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "nbdev jupyter notebook python",
    "author": "ncoop57",
    "author_email": "nc@answer.ai",
    "download_url": "https://files.pythonhosted.org/packages/20/46/08f84b41cff7322e41ad0b2b2df1e78ae863708df53af3489d28a04985ac/shell_sage-0.0.7.tar.gz",
    "platform": null,
    "description": "# ShellSage\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n## Overview\n\nShellSage works by understanding your terminal context and leveraging\npowerful language models (Claude or GPT) to provide intelligent\nassistance for:\n\n- Shell commands and scripting\n- System administration tasks\n- Git operations\n- File management\n- Process handling\n- Real-time problem solving\n\nWhat sets ShellSage apart is its ability to:\n\n- Read your terminal context through tmux integration\n- Provide responses based on your current terminal state\n- Accept piped input for direct analysis\n- Target specific tmux panes for focused assistance\n\nWhether you\u2019re a seasoned sysadmin or just getting started with the\ncommand line, ShellSage acts as your intelligent terminal companion,\nready to help with both simple commands and complex operations.\n\n## Installation\n\nInstall ShellSage directly from PyPI using pip:\n\n``` sh\npip install shell_sage\n```\n\n### Prerequisites\n\n1.  **API Key Setup**\n\n    ``` sh\n    # For Claude (default)\n    export ANTHROPIC_API_KEY=sk...\n\n    # For OpenAI (optional)\n    export OPENAI_API_KEY=sk...\n    ```\n\n2.  **tmux Configuration**\n\n    We recommend using this optimized tmux configuration for the best\n    ShellSage experience. Create or edit your `~/.tmux.conf`:\n\n    ``` sh\n    # Enable mouse support\n    set -g mouse on\n\n    # Show pane ID and time in status bar\n    set -g status-right '#{pane_id} | %H:%M '\n\n    # Keep terminal content visible (needed for neovim)\n    set-option -g alternate-screen off\n\n    # Enable vi mode for better copy/paste\n    set-window-option -g mode-keys vi\n\n    # Improved search and copy bindings\n    bind-key / copy-mode\\; send-key ?\n    bind-key -T copy-mode-vi y \\\n      send-key -X start-of-line\\; \\\n      send-key -X begin-selection\\; \\\n      send-key -X end-of-line\\; \\\n      send-key -X cursor-left\\; \\\n      send-key -X copy-selection-and-cancel\\; \\\n      paste-buffer\n    ```\n\n    Reload tmux config:\n\n    ``` sh\n    tmux source ~/.tmux.conf\n    ```\n\nThis configuration enables mouse support, displays pane IDs (crucial for\ntargeting specific panes), maintains terminal content visibility, and\nadds vim-style keybindings for efficient navigation and text selection.\n\n## Getting Started\n\n### Basic Usage\n\nShellSage is designed to run within a tmux session. Here are the core\ncommands:\n\n``` sh\n# Basic usage\nssage hi ShellSage\n\n# Pipe content to ShellSage\ncat error.log | ssage explain this error\n\n# Target a specific tmux pane\nssage --pid %3 what is happening in this pane?\n\n# Automatically fill in the command to run\nssage --c how can I list all files including the hidden ones?\n```\n\nThe `--pid` flag is particularly useful when you want to analyze content\nfrom a different pane. The pane ID is visible in your tmux status bar\n(configured earlier).\n\n### Using Alternative Model Providers\n\nShellSage supports using different LLM providers through base URL\nconfiguration. This allows you to use local models or alternative API\nendpoints:\n\n``` sh\n# Use a local Ollama endpoint\nssage --provider openai --model llama3.2 --base_url http://localhost:11434/v1 --api_key ollama what is rsync?\n\n# Use together.ai\nssage --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\n```\n\nThis is particularly useful for:\n\n- Running models locally for privacy/offline use\n- Using alternative hosting providers\n- Testing different model implementations\n- Accessing specialized model deployments\n\nYou can also set these configurations permanently in your ShellSage\nconfig file (`~/.config/shell_sage/shell_sage.conf`). See next section\nfor details.\n\n## Configuration\n\nShellSage can be customized through its configuration file located at\n`~/.config/shell_sage/shell_sage.conf`. Here\u2019s a complete configuration\nexample:\n\n``` ini\n[DEFAULT]\n# Choose your AI model provider\nprovider = anthropic     # or 'openai'\nmodel = claude-3-5-sonnet-20241022 # or 'gpt-4o-mini' for OpenAI\nbase_url = # leave empty to use default openai endpoint\napi_key = # leave empty to default to using your OPENAI_API_KEY env var\n\n# Terminal history settings\nhistory_lines = -1      # -1 for all history\n\n# Code display preferences\ncode_theme = monokai    # syntax highlighting theme\ncode_lexer = python     # default code lexer\n```\n\nYou can find all of the code theme and code lexer options here:\nhttps://pygments.org/styles/\n\n### Command Line Overrides\n\nAny configuration option can be overridden via command line arguments:\n\n``` sh\n# Use OpenAI instead of Claude for a single query\nssage --provider openai --model gpt-4o-mini \"explain this error\"\n\n# Adjust history lines for a specific query\nssage --history-lines 50 \"what commands did I just run?\"\n```\n\n## Tips & Best Practices\n\n### Effective Usage Patterns\n\n1.  **Contextual Queries**\n\n    - Keep your tmux pane IDs visible in the status bar\n    - Use `--pid` when referencing other panes\n    - Let ShellSage see your recent command history for better context\n\n2.  **Piping Best Practices**\n\n    ``` sh\n    # Pipe logs directly\n    tail log.txt | ssage \"summarize these logs\"\n\n    # Combine commands\n    git diff | ssage \"review these changes\"\n    ```\n\n### Getting Help\n\n``` sh\n# View all available options\nssage --help\n\n# Submit issues or feature requests\n# https://github.com/AnswerDotAI/shell_sage/issues\n```\n\n## Contributing\n\nShellSage is built using [nbdev](https://nbdev.fast.ai/). For detailed\ncontribution guidelines, please see our\n[CONTRIBUTING.md](CONTRIBUTING.md) file.\n\nWe welcome contributions of all kinds:\n\n- Bug reports\n- Feature requests\n- Documentation improvements\n- Code contributions\n\nPlease visit our [GitHub\nrepository](https://github.com/AnswerDotAI/shell_sage) to get started.\n",
    "bugtrack_url": null,
    "license": "Apache Software License 2.0",
    "summary": "Your favorite AI buddy right in your terminal",
    "version": "0.0.7",
    "project_urls": {
        "Homepage": "https://github.com/AnswerDotAI/shell_sage"
    },
    "split_keywords": [
        "nbdev",
        "jupyter",
        "notebook",
        "python"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "700a01625bb310e54621068566b17f1f6d5028868e551c1ab37e9003ec9afb95",
                "md5": "fb58a2eafd829a1f9e250b390ce761ec",
                "sha256": "257bb189480761e28c650d25ff4b628e7cc1c2cb22cd71a94b46f17afa9e9ba5"
            },
            "downloads": -1,
            "filename": "shell_sage-0.0.7-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fb58a2eafd829a1f9e250b390ce761ec",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 13846,
            "upload_time": "2025-02-01T15:09:16",
            "upload_time_iso_8601": "2025-02-01T15:09:16.732361Z",
            "url": "https://files.pythonhosted.org/packages/70/0a/01625bb310e54621068566b17f1f6d5028868e551c1ab37e9003ec9afb95/shell_sage-0.0.7-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "204608f84b41cff7322e41ad0b2b2df1e78ae863708df53af3489d28a04985ac",
                "md5": "d9d27abf4b6c31594257182a34bed83d",
                "sha256": "2a0e2bc6276f88d8417ec2aaa1d326e845e54830b9f75b7e92cdecf7d1d99406"
            },
            "downloads": -1,
            "filename": "shell_sage-0.0.7.tar.gz",
            "has_sig": false,
            "md5_digest": "d9d27abf4b6c31594257182a34bed83d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 18345,
            "upload_time": "2025-02-01T15:09:17",
            "upload_time_iso_8601": "2025-02-01T15:09:17.782302Z",
            "url": "https://files.pythonhosted.org/packages/20/46/08f84b41cff7322e41ad0b2b2df1e78ae863708df53af3489d28a04985ac/shell_sage-0.0.7.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-01 15:09:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "AnswerDotAI",
    "github_project": "shell_sage",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "shell-sage"
}
        
Elapsed time: 0.58774s