My Command-Line AI Assistant

How I use Shell Sage to bring AI assistance directly into my terminal workflow.
Author

Sjoerd de Haan

Published

November 25, 2025

AI at the command line

Most work I do via the command line.

I found LLM’s very helpfull to

  • Quicly get help with commands
  • Explain principles behind tools
  • Come up with a complicated regex solution
  • Suggest various ways to solve a problem

The added cost is switching between the terminal and the browswer, copying ocntent back and forth.

I’m allways working in tmux sessions with multiple panes open. This allows quick context switching between terminals, but does still take time to gather sufficient context to ask a good question to an LLM.

Shell sage solves most of those problems.

Shell Sage: My Command-Line AI Assistant

Shell Sage (ssage) is a command-line tool that brings Claude (or other LLMs) directly into my terminal workflow. Source code is on GitHub. It’s particularly useful for my day to day tasks on Arch, where I’m constantly juggling tmux panes, debugging services, and working with git repositories.

What Makes It Useful

Shell Sage automatically reads my tmux pane history, so it has context about what I’ve been doing. When something goes wrong, I can just type ssage what went wrong? and it sees my recent commands and their output.

Setup

Install and configure with your Anthropic API key:

export ANTHROPIC_API_KEY="your-key-here"

Config lives at ~/.config/shell_sage/shell_sage.conf where you can set defaults for model, theme, and history length.

My Common Workflows

Debugging systemd services:

journalctl -u some-service --since "10 minutes ago" --no-pager | ssage explain these errors

Learning new command options:

Sometimes shell sage is faster than going to the man pages:

ssage how do I use rg to search only in specific file types?
ssage show me fd examples for finding files modified in the last week

This I found is especially true for commands with extensive options, like ffmpeg, rsync, or git.

Git workflows:

ssage how do I cherry-pick a range of commits?
ssage explain the difference between git annex sync and git annex copy

Docker debugging:

docker logs container-name | ssage why is this container crashing?
ssage how do I clean up unused docker volumes safely?

Sway/Wayland tasks:

ssage how do I capture a specific window with grim and slurp?
ssage show me how to pipe screenshot to wl-copy

Tmux Integration

Since I live in tmux, the automatic context awareness is huge. Shell Sage reads my current pane’s history, so it knows: - What commands I just ran - What errors appeared - What I was trying to do

If I need to reference a different pane:

ssage --pid %2 what's happening in that pane?

Fish Shell Integration

For repetitive tasks, I create fish functions that incorporate ssage:

function explain-last
    ssage explain what went wrong with my last command
end

Command-Line Options I Use

Adjust context window:

ssage --history_lines 200 analyze my recent workflow

Different modes:

Shell Sage has two modes: default and sassy.

ssage --mode command give me a one-liner to find all systemd services that failed today

Piping with bat/rg output:

rg "ERROR" --context 3 | ssage summarize these errors
bat some-config.conf | ssage is this configuration correct?

Why It Works for My Workflow

  1. Context-aware: Sees my tmux history automatically
  2. Pipe-friendly: Works naturally with rg, fd, journalctl, docker logs, etc.
  3. Fast: Quick answers without leaving the terminal
  4. Arch-friendly: Understands systemctl, pacman, and other Arch-specific tools
  5. Git annex help: Useful for the more obscure git-annex commands

Tips

  • Use --log to keep a record of all interactions
  • Pipe command output directly to ssage instead of copying/pasting
  • Ask follow-up questions - it remembers the context within tmux
  • Works great with neovim’s :! command execution

Shell Sage has become an essential part of my terminal workflow, especially for those moments when I need quick help without context-switching to a browser or documentation.