# 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"
}
JSON
