Shell History Semantic Search

A privacy-first CLI tool that indexes shell command history and enables natural language semantic search using local embeddings. Search your shell history using queries like "how to undo last commit" instead of remembering exact commands.

Features

• 🔍 Semantic Search - Search shell history using natural language queries
• 🔒 Privacy-First - All processing happens locally, no data leaves your machine
• 🐚 Multi-Shell Support - Supports bash, zsh, and fish shells
• ⚡ Local Embeddings - Uses sentence-transformers for semantic understanding
• 📊 CLI Interface - Simple and intuitive command-line interface

Installation

pip install shell-history-search

Or install from source:

git clone <repository-url>
cd shell-history-semantic-search
pip install -e .

Quick Start

# Index your shell history
shell-history-search index

# Search using natural language
shell-history-search search "how to undo last commit"
shell-history-search search "push to remote"
shell-history-search search "find large files"

Commands

Command	Description
index	Index shell history from bash, zsh, and fish
search <query>	Search indexed commands using natural language
stats	Show indexing statistics
clear	Clear all indexed data

Index Command

# Index all shells
shell-history-search index

# Index specific shell only
shell-history-search index --shell bash

Search Command

# Basic search
shell-history-search search "undo last commit"

# Limit results
shell-history-search search "docker" --limit 5

# Filter by shell
shell-history-search search "git" --shell bash

# JSON output
shell-history-search search "compile" --json

Stats Command

shell-history-search stats

Clear Command

shell-history-search clear

Privacy

All processing happens locally with no data leaving your machine:

• No external API calls
• Database stored locally at ~/.local/share/shell_history_search/history.db
• No telemetry or tracking
• Embedding model downloaded once on first run

Configuration

Environment Variables

Variable	Default	Description
SHELL_HISTORY_DB	~/.local/share/shell_history_search/history.db	Database path
SHELL_HISTORY_MODEL_CACHE	~/.cache/shell_history_search/models	Model cache directory
SHELL_HISTORY_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARNING, ERROR)

Architecture

src/shell_history_search/
├── cli/          # Click CLI interface
├── core/         # Business logic (embeddings, search, indexing)
├── db/           # SQLite database management
└── parsers/      # Shell history parsers (bash, zsh, fish)

Components

• EmbeddingService: Generates semantic embeddings using sentence-transformers
• SearchEngine: Performs vector similarity search
• IndexingService: Parses and indexes shell history files
• Parsers: Support for bash, zsh, and fish history formats

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src/shell_history_search --cov-report=term-missing

Troubleshooting

sqlite-vss extension not installed

The tool falls back to manual cosine similarity calculation using numpy if sqlite-vss is not available. All functionality remains available.

No history files found

The tool looks for history files at these locations:

• Bash: ~/.bash_history
• Zsh: ~/.zsh_history
• Fish: ~/.local/share/fish/fish_history

Ensure you have shell history enabled and history has been written.

Model download fails

On first run, the embedding model (~22MB) will be downloaded and cached. If download fails, check your internet connection and try again.

License

MIT License