Skip to content

Commit 5602a64

Browse files
author
ncoop57
committed
Update README and documentation with comprehensive usage guide
1 parent 26dc9be commit 5602a64

File tree

7 files changed

+440
-56
lines changed

7 files changed

+440
-56
lines changed

‎README.md

Lines changed: 146 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,181 @@
11
# ShellSage
22

3-
## Usage
43

5-
### Installation
4+
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
65

7-
Install latest from the GitHub
8-
[repository](https://github.com/AnswerDotAI/shell_sage):
6+
## Overview
97

10-
or from [pypi](https://pypi.org/project/shell_sage/)
8+
ShellSage works by understanding your terminal context and leveraging
9+
powerful language models (Claude or GPT) to provide intelligent
10+
assistance for:
1111

12-
```sh
12+
- Shell commands and scripting
13+
- System administration tasks
14+
- Git operations
15+
- File management
16+
- Process handling
17+
- Real-time problem solving
18+
19+
What sets ShellSage apart is its ability to: - Read your terminal
20+
context through tmux integration - Provide responses based on your
21+
current terminal state - Accept piped input for direct analysis - Target
22+
specific tmux panes for focused assistance
23+
24+
Whether you’re a seasoned sysadmin or just getting started with the
25+
command line, ShellSage acts as your intelligent terminal companion,
26+
ready to help with both simple commands and complex operations.
27+
28+
## Installation
29+
30+
Install ShellSage directly from PyPI using pip:
31+
32+
``` sh
1333
pip install shell_sage
1434
```
1535

16-
We recommend also setting up your terminal editor of choice to keep the editor content's displayed in the terminal on exit. This allows `ShellSage` to see the files you have been working on. Here is how you can do this in vim:
36+
### Prerequisites
1737

18-
```sh
19-
echo "set t_ti= t_te=" >> ~/.vimrc
20-
```
38+
1. **API Key Setup**
2139

22-
for `neovim` the above won't work.. but you can set it up in tmux:
40+
``` sh
41+
# For Claude (default)
42+
export ANTHROPIC_API_KEY=sk...
2343

24-
```
25-
set-option -g alternate-screen off
26-
```
44+
# For OpenAI (optional)
45+
export OPENAI_API_KEY=sk...
46+
```
2747

28-
You will also need to get an Anthropic API key and set its environment variable:
48+
2. **tmux Configuration**
2949

30-
```sh
31-
export ANTHROPIC_API_KEY=sk...
32-
```
50+
We recommend using this optimized tmux configuration for the best
51+
ShellSage experience. Create or edit your `~/.tmux.conf`:
52+
53+
``` sh
54+
# Enable mouse support
55+
set -g mouse on
56+
57+
# Show pane ID and time in status bar
58+
set -g status-right '#{pane_id} | %H:%M '
59+
60+
# Keep terminal content visible (needed for neovim)
61+
set-option -g alternate-screen off
62+
63+
# Enable vi mode for better copy/paste
64+
set-window-option -g mode-keys vi
65+
66+
# Improved search and copy bindings
67+
bind-key / copy-mode\; send-key ?
68+
bind-key -T copy-mode-vi y \
69+
send-key -X start-of-line\; \
70+
send-key -X begin-selection\; \
71+
send-key -X end-of-line\; \
72+
send-key -X cursor-left\; \
73+
send-key -X copy-selection-and-cancel\; \
74+
paste-buffer
75+
```
76+
77+
Reload tmux config:
78+
79+
``` sh
80+
tmux source ~/.tmux.conf
81+
```
82+
83+
This configuration enables mouse support, displays pane IDs (crucial for
84+
targeting specific panes), maintains terminal content visibility, and
85+
adds vim-style keybindings for efficient navigation and text selection.
86+
87+
## Getting Started
3388

34-
## How to use
89+
### Basic Usage
3590

36-
`ShellSage` is designed to be ran inside a tmux session since it relies on tmux for getting what has is displayed on your terminal as context. If you don't want to use tmux, you will need to use the `--NH` command, which will not include your terminal history.
91+
ShellSage is designed to run within a tmux session. Here are the core
92+
commands:
3793

38-
```sh
94+
``` sh
95+
# Basic usage
3996
ssage hi ShellSage
40-
```
4197
42-
```markdown
43-
Hello! I'm ShellSage, your command-line assistant. I can help you with:
98+
# Pipe content to ShellSage
99+
cat error.log | ssage explain this error
44100
45-
- Bash commands and scripting
46-
- System administration tasks
47-
- Git operations
48-
- File management
49-
- Process handling
50-
- And more!
101+
# Target a specific tmux pane
102+
ssage --pid %3 what's happening in this pane?
51103
```
52104
53-
You can also pipe outputs into `ShellSage`:
105+
The `--pid` flag is particularly useful when you want to analyze content
106+
from a different pane. The pane ID is visible in your tmux status bar
107+
(configured earlier).
54108
55-
```sh
56-
cat file.txt | ssage summarize this file
57-
```
109+
## Configuration
58110
59-
You can also select a specific pane for context to come from instead of the default current pane.
111+
ShellSage can be customized through its configuration file located at
112+
`~/.config/shell_sage/shell_sage.conf`. Here’s a complete configuration
113+
example:
60114
61-
```sh
62-
ssage --pid %3 your question
115+
``` ini
116+
[DEFAULT]
117+
# Choose your AI model provider
118+
provider = anthropic # or 'openai'
119+
model = claude-3-sonnet # or 'gpt-4o-mini' for OpenAI
120+
121+
# Terminal history settings
122+
history_lines = -1 # -1 for all history
123+
124+
# Code display preferences
125+
code_theme = monokai # syntax highlighting theme
126+
code_lexer = python # default code lexer
63127
```
64128
65-
> Tip: To use the pane-id selection feature, it is helpful to add `set -g status-right '#{pane_id}'` to your `~/.tmux.conf` file. Once done, you can reload your tmux config with `tmux source ~/.tmux.conf` to have the pane id displayed on the right hand side of your tmux status bar.
129+
### Command Line Overrides
66130
67-
### Configuration
131+
Any configuration option can be overridden via command line arguments:
68132
69-
Sage uses a configuration file located at `~/.config/shell_sage/shell_sage.conf`. You can overwrite these configurations by modifying this file or by passing the ShellSage CLI tool a specific argument. By default, ShellSage will use Anthropic's Claude Sonnet 3.5 model. However, you can also use any OpenAI model as well. For example, you can modify your configuration file to be the following:
133+
``` sh
134+
# Use OpenAI instead of Claude for a single query
135+
ssage --provider openai --model gpt-4o-mini "explain this error"
70136
71-
```
72-
[DEFAULT]
73-
model = gpt-4o-mini
74-
provider = openai
75-
history_lines = -1
76-
code_theme = monokai
77-
code_lexer = python
78-
sassy_mode = False
137+
# Adjust history lines for a specific query
138+
ssage --history-lines 50 "what commands did I just run?"
79139
```
80140
81-
And now when you run ShellSage, it will use GPT 4o mini rather than Cloud Sonnet 3.5. From the command line, you could also do this:
141+
## Tips & Best Practices
82142
83-
```sh
84-
ssage hi --provider openai --model gpt-4o-mini
143+
### Effective Usage Patterns
144+
145+
1. **Contextual Queries**
146+
147+
- Keep your tmux pane IDs visible in the status bar
148+
- Use `--pid` when referencing other panes
149+
- Let ShellSage see your recent command history for better context
150+
151+
2. **Piping Best Practices**
152+
153+
``` sh
154+
# Pipe logs directly
155+
tail -f log.txt | ssage "watch for errors"
156+
157+
# Combine commands
158+
git diff | ssage "review these changes"
159+
```
160+
161+
### Getting Help
162+
163+
``` sh
164+
# View all available options
165+
ssage --help
166+
167+
# Submit issues or feature requests
168+
# https://github.com/AnswerDotAI/shell_sage/issues
85169
```
86170
87-
Remember, this does require you to have set up your OpenAI API key as an environment variable.
171+
## Contributing
172+
173+
ShellSage is built using [nbdev](https://nbdev.fast.ai/). For detailed
174+
contribution guidelines, please see our
175+
[CONTRIBUTING.md](CONTRIBUTING.md) file.
176+
177+
We welcome contributions of all kinds: - Bug reports - Feature
178+
requests - Documentation improvements - Code contributions
179+
180+
Please visit our [GitHub
181+
repository](https://github.com/AnswerDotAI/shell_sage) to get started.

‎nbs/00_core.ipynb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -601,15 +601,15 @@
601601
" query: Param('The query to send to the LLM', str, nargs='+'),\n",
602602
" pid: str = 'current', # `current`, `all` or tmux pane_id (e.g. %0) for context\n",
603603
" skip_system: bool = False, # Whether to skip system information in the AI's context\n",
604-
" n: int = None, # Number of history lines. Defaults to tmux scrollback history length\n",
604+
" history_lines: int = None, # Number of history lines. Defaults to tmux scrollback history length\n",
605605
" s: bool = False, # Enable sassy mode\n",
606606
" provider: str = None, # The LLM Provider\n",
607607
" model: str = None, # The LLM model that will be invoked on the LLM provider\n",
608608
" code_theme: str = None, # The code theme to use when rendering ShellSage's responses\n",
609609
" code_lexer: str = None, # The lexer to use for inline code markdown blocks\n",
610610
" verbosity: int = 0 # Level of verbosity (0 or 1)\n",
611611
"): \n",
612-
" opts = get_opts(history_lines=n, provider=provider, model=model,\n",
612+
" opts = get_opts(history_lines=history_lines, provider=provider, model=model,\n",
613613
" code_theme=code_theme, code_lexer=code_lexer)\n",
614614
" \n",
615615
" if verbosity>0:\n",

‎nbs/_quarto.yml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
project:
2+
type: website
3+
4+
format:
5+
html:
6+
theme: cosmo
7+
css: styles.css
8+
toc: true
9+
keep-md: true
10+
commonmark: default
11+
12+
website:
13+
twitter-card: true
14+
open-graph: true
15+
repo-actions: [issue]
16+
navbar:
17+
background: primary
18+
search: true
19+
sidebar:
20+
style: floating
21+
22+
metadata-files: [nbdev.yml, sidebar.yml]

0 commit comments

Comments
 (0)