/shell-history-semantic-search

Search you bash, zsh, fish shell history using semantic search

Primary LanguagePython

Bash History Semantic Search

A command-line tool to semantically search your shell command history using OpenAI embeddings. Find commands based on natural language descriptions instead of exact text matches. Supports multiple shells including Bash, Zsh, and Fish.

Features

  • Semantic search using OpenAI embeddings
  • Supports multiple shell history files (Bash, Zsh, Fish)
  • Deduplicates commands across different shells
  • Persists embeddings locally for fast subsequent searches
  • Shows similarity scores for each result
  • Supports refreshing the database with latest history

Prerequisites

  • Python 3.8+
  • OpenAI API key
  • One or more of these shells installed:
    • Bash (~/.bash_history)
    • Zsh (~/.zsh_history)
    • Fish (~/.local/share/fish/fish_history)

Installation

  1. Clone this repository:
git clone https://github.com/yourusername/bash-history-search.git
cd bash-history-search
  1. Install dependencies:
pip install -r requirements.txt
  1. Create a .env file in the project root and add your OpenAI API key:
OPENAI_API_KEY=your_api_key_here

Usage

Basic search:

python bash_search.py "find files containing text"

Search with custom number of results:

python bash_search.py "git commands" --num 10

Refresh the database with latest shell history:

python bash_search.py "your query" --refresh

How it Works

  1. The tool reads command history from multiple sources:
    • Bash history from ~/.bash_history
    • Zsh history from ~/.zsh_history
    • Fish history from ~/.local/share/fish/fish_history
  2. Commands are deduplicated across all sources
  3. Each unique command is embedded using OpenAI's text-embedding-3-small model
  4. Embeddings are stored locally using ChromaDB
  5. When searching, your query is embedded and compared with stored command embeddings
  6. Most similar commands are returned with their similarity scores

Options

  • query: Your search query in natural language (required)
  • --num, -n: Number of results to return (default: 5)
  • --refresh, -r: Refresh the database with latest shell history

Example Output

Most similar commands:
grep -r "search text" .
Similarity: 0.892

find . -type f -exec grep "pattern" {} \;
Similarity: 0.857

ag "search string" --ignore-dir node_modules
Similarity: 0.843

Shell History File Locations

The tool will automatically look for history files in these default locations:

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

If your shell history files are in different locations, you can modify the paths in the code.

License

MIT