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