# 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's happening in this pane?
```
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).
## 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-sonnet # or 'gpt-4o-mini' for OpenAI
# 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
```
### 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 -f log.txt | ssage "watch for errors"
# 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/5a/70/7df0db560d9f7f7522640146f0b8b5255d974f86efe4ec95eb43e2dc19eb/shell_sage-0.0.5.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: - Read your terminal\ncontext through tmux integration - Provide responses based on your\ncurrent terminal state - Accept piped input for direct analysis - Target\nspecific 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's happening in this pane?\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## 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-sonnet # or 'gpt-4o-mini' for OpenAI\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\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 -f log.txt | ssage \"watch for errors\"\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: - Bug reports - Feature\nrequests - Documentation improvements - 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.5",
"project_urls": {
"Homepage": "https://github.com/AnswerDotAI/shell_sage"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a1ffeb7c505bd3962ccecdfeb731ed385b7b958df846e264748ccbcc0b5bf41",
"md5": "5fe817be78178e0155328247376151ae",
"sha256": "bb080b7ddfd8216de287a240b6f43d1cca5e531377edff1a9e1b609f17459e6c"
},
"downloads": -1,
"filename": "shell_sage-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5fe817be78178e0155328247376151ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12660,
"upload_time": "2024-12-19T16:38:40",
"upload_time_iso_8601": "2024-12-19T16:38:40.181275Z",
"url": "https://files.pythonhosted.org/packages/9a/1f/feb7c505bd3962ccecdfeb731ed385b7b958df846e264748ccbcc0b5bf41/shell_sage-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a707df0db560d9f7f7522640146f0b8b5255d974f86efe4ec95eb43e2dc19eb",
"md5": "246e290a7d4e47ff9b2d18e8a5c04029",
"sha256": "9f7913ea10e44824a123f2302e0cecebedff1eeaefadf8fe46cef599fac6aca0"
},
"downloads": -1,
"filename": "shell_sage-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "246e290a7d4e47ff9b2d18e8a5c04029",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16594,
"upload_time": "2024-12-19T16:38:42",
"upload_time_iso_8601": "2024-12-19T16:38:42.226945Z",
"url": "https://files.pythonhosted.org/packages/5a/70/7df0db560d9f7f7522640146f0b8b5255d974f86efe4ec95eb43e2dc19eb/shell_sage-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-19 16:38:42",
"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
