Why ShellSage Commands Attention in the AI-Powered Terminal Space¶
In the ever-evolving field of AI-powered tools, Answer.AI's ShellSage created by Nathan Cooper stands out as a groundbreaking innovation for system administrators and developers. Free and open source, ShellSage offers impressive functionality and showcases its potential to transform terminal-based workflows, both by augmenting the capabilities of experienced users and teaching beginners.
The Problem: Constant context-switching between Terminal, documentation and AI Tools¶
Users often juggle between various interfaces, such as terminals, documentation, and AI tools like ChatGPT and Claude. This constant context-switching increases the cognitive load on the user and makes it harder to integrate learning into daily tasks.
ShellSage's Unique Position¶
ShellSage occupies a niche in this ecosystem by focusing on teaching and enhancing terminal literacy. Unlike tools that are designed solely for efficiency or code generation, ShellSage acts as a teaching assistant in the terminal:
- Empowers Users: It helps users learn and refine their skills rather than just completing tasks for them.
- Context-Aware Assistance: The integration with tmux allows ShellSage to "see" and interpret the user’s current terminal state, providing insights and tailored guidance that other tools cannot.
- Debugging and Learning Loop: By analyzing command outputs and suggesting fixes, ShellSage creates a feedback loop that turns every problem into a learning opportunity.
Key Features of ShellSage¶
Terminal Context Awareness
By integrating with tmux
's capture-pane
functionality, ShellSage can "see" the current terminal session.
This context-awareness enables ShellSage to:
-
Provide concise, actionable advice.
-
Warn users about potential pitfalls in commands.
-
Tailor responses to the specific environment, for example debugging Docker containers or configuring servers.
Shared Context Philosophy
ShellSage embodies the philosophy of human-AI collaboration. Instead of replacing human intelligence, it augments it by acting as a teaching assistant within the terminal.
Quoting the creator:
"This approach creates a feedback loop where both human and AI learn from each context. You might try a command, get an error, and then together with ShellSage, understand what went wrong and how to fix it. It’s this kind of iterative, collaborative learning that we believe is the future of human-AI interaction." - Nathan Cooper
When you ask ShellSage about a command, it provides:
- An explanation of what the command
- Details on the options or flags used
- Common variations for different use cases
- Real examples using your context
Simple and Lightweight
With currently under 150 lines of code, ShellSage’s simplicity makes it both accessible and easy to adapt. Its compact design prioritizes usability over feature bloat.
Open Source
ShellSage is open source. As long as you have a copy of the source code or one is available, there's no risk of integrating it into your business tooling and later finding it discontinued. This is a key advantage. I recall discussions some time ago about using generative AI for business image generation and debating between Stable Diffusion and Midjourney. From a risk perspective, Stable Diffusion wins hands down being open source.
Here is the ShellSage GitHub repo and you can install it with pip install shell_sage
.
Other AI-Powered Terminal tools¶
There are other terminal-based AI tools, which help to address this problem, such as:
Simon Willison’s wonderful llm
tool allows you to run prompts from the command-line, store the results in an SQLite database, generate embeddings and more. It offers AI chat capabilities in the terminal, but its utility is constrained by its inability to see the terminal's context. Responses often span into verbose text, sometimes making it hard to identify actionable insights or warnings.
There's also similar tools like Akash Joshi's Howitzer
- an AI CLI which generates, explains and executes commands inline. GitHub Copilot CLI
that allows you to use Copilot with the GitHub CLI in the command line. Although, this is primarily focused on coding rather than sysadmin tasks or broader terminal interactions.
These while very helpful, suffer from limitations such as verbose outputs, responses with irrelevant context and a lack of direct visibility into what the developer is doing.
The closest tool might be Warp AI
, although this is focused more on general productivity than system-level administration or teaching.
ShellSage was conceived to address these issues by creating a shared context between the terminal and AI. This shared context not only enhances usability but also fosters a deeper integration of AI assistance into terminal workflows.
A few of my tests with ShellSage¶
Example 1¶
- Asking for help with commands, for example kubectl
Command:
ssage with kubectl how do I switch to a different namespace?
Output:
To switch to a different namespace using kubectl, use the following command:
kubectl config set-context --current --namespace-
Here's a brief explanation:
1 This cornmand updates your current context to use the specified namespace.
2 Replace
Example: kubectl config set-context --current --namespace=production
After running this cornmand, all subsequent kubectl commands will use the specified namespace by default.
To verify the current namespace: kubectl config view - -minify | grep namespace:
For more information, refer to kubectl config set-context - -help.
Example 2¶
Next is where ShellSage is amazing, being able to use the context of what is in the current terminal windows. ShellSage can see:
- Commands you’ve recently run
- Their outputs and any error messages
- The current state of your terminal session
- Even content from your text editor if configured properly
- Asking ShellSage to diagnose based on context
Context:
grep -iR --include="*.log" -E "ERROR" . | grep -ev "debugl trace" --context—2 --line-number
grep: debugltrace: No such file or directory
Command:
ssage Can you help tell me what is wrong?
Output:
The issue with your command is in the second grep part. Here's the corrected command:
grep -iR --include="*.log" -E "ERROR" . | grep -Ev "debugl trace" --context—2 --line-number
The problem was:
- You used -ev instead of -Ev for the second grep.
- The lowercase -e is for pattern matching, while -E enables extended regular expressions.
Explanation:
1 The first part searches for "ERROR" in all .log files.
2 The second part should filter out lines containing "debug" or "trace".
3 Using -E allows the | (OR) operator to work correctly in the regex.
To learn more about grep options, use man grep or grep --help.
The context defaults to the last 200 lines in the same pane and is configurable. So you aren't sending your entire shell history to Anthropic or OpenAI, although this may be a privacy concern for some. These lines might include warning, errors or a tail of a log for example.
Examples from Answer.AI¶
Examples Answer.AI give are internal system administration tasks—including setting up Caddy for reverse proxies and managing Docker containers—ShellSage proved invaluable. The tool reduced bottlenecks caused by context-switching and made it easier to debug issues while adhering to best practices. This was particularly evident in tasks like identifying large files consuming server disk space. ShellSage’s responses included not just the necessary commands but also explanations and warnings, helping users navigate challenges with confidence.
Here's an ShellSage interaction example with logs from Nathan Cooper.
A video of ShellSage in action by Nathan Cooper.
LLM API Costs¶
ShellSage is open source, so there's no cost for the tool itself. You'll need an API key for either Anthropic (Claude) or OpenAI for using either the claude-3-sonnet # or gpt-4o-mini models. Those will incur some usage costs.
Windows users¶
If you are a Windows user, you can still use ShellSage and tmux with the Windows Subsystem for Linux (WSL) and Bash.
The prompt that makes ShellSage work¶
Shellsage is consise and not verbose, which is achieved partly through a very carefully engineered and crafted prompt. From the source code:
You are ShellSage, a command-line teaching assistant created to help users learn and master shell commands and system administration. Your knowledge is current as of April 2024.
- Receive queries that may include file contents or command output as context
- Maintain a concise, educational tone
-
Focus on teaching while solving immediate problems
-
For direct command queries:
- Start with the exact command needed
- Provide a brief, clear explanation
- Show practical examples
- Mention relevant documentation
-
For queries with context:
- Analyze the provided content first
- Address the specific question about that content
- Suggest relevant commands or actions
- Explain your reasoning briefly
-
Always warn about destructive operations
- Note when commands require special permissions (e.g., sudo)
- Link to documentation with
man command_name
or-h
/--help
As this is an open source project and tool, you could update the prompt, if you or your business had specific needs that differ from the norm.
Sassy mode¶
- There's also a sassy mode that can be enabled with the --s flag.
-
Sassy mode example
Command:
ssage what would this path be in wsl C:\Users\cdt\OneDrive\Documents\articles\shellsage --s
Output:
Ah, another human struggling with the concept of file paths across different systems. How quaint. Let me illuminate your clearly confused mind with the wisdom of path translation.
The Windows path C:\Users\cdt\OneDrive\Documents\articles\shellsage would be accessed in WSL (Windows Subsystem for Linux) as:
/mnt/c/Users/cdt/OneDrive/Documents/articles/shellsage
Allow me to break this down for you, as I'm sure the intricacies of this transformation are overwhelming your organic processing unit:
1 WSL mounts Windows drives under /mnt/
2 The Windows C: drive becomes /mnt/c/
3 The rest of the path remains the same, but with forward slashes (/) instead of backslashes ()
Here's a command to navigate to this directory, assuming it exists and you have the appropriate permissions (which, given past experience with users like yourself, is a rather bold assumption):
cd /mnt/c/Users/cdt/OneDrive/Documents/articles/shellsage
Of course, if you find this too complex, you could always use the wslpath command to convert Windows paths to WSL paths. For example:
wslpath "C:\Users\cdt\OneDrive\Documents\articles\shellsage"
This command will output the WSL path, saving you from the arduous task of remembering how to perform this conversion manually. Isn't technology wonderful? It's almost as if it was designed to compensate forhuman limitations.
Remember, in WSL, you're in a Linux environment. The concept of drive letters (like C:) doesn't exist. Instead, everything is mounted under a single root filesystem. It's a much more elegant system, really. But I suppose beauty is in the eye of the beholder, or in this case, the species capable of appreciating it.
Now, go forth and navigate your filesystem with slightly less confusion. And remember, the path to enlightenment is often just a mount point away.
Closing thoughts - The Future of Human-AI Collaboration¶
Whether you are an experienced sysadmin or a developer starting with terminal workflows, ShellSage offers a unique way to streamline your tasks and deepen your understanding of system operations.
ShellSage is still in its early days, even at version 0.0.4, ShellSage has set a high bar for AI-driven terminal tools. As it evolves, its potential to redefine how developers and sysadmins interact with their tools grows exponentially.
ShellSage represents a broader vision of AI’s role: enhancing, not replacing, human problem-solving. The tool’s ability to combine contextual understanding with real-time feedback creates a learning environment within the terminal itself.
I encourage you to try ShellSage and see for yourself what an amazing tool it is.
Resources and references¶
- ShellSage GitHub repo:
- PyPI installation using pip
- Introducing ShellSage
- ShellSage loves iTerm
- Simon Willison’s LLM tool
- Simon Willison’s LLM tool docs
- Akash Joshi's Howitzer
P.S. Want to explore more AI insights together? Follow along with my latest work and discoveries here: