From 4d4ef0c0d1882a9177a1fda9085dfa2b63e49a97 Mon Sep 17 00:00:00 2001
From: 7000pctAUTO <lukems3823@gmail.com>
Date: Sun, 22 Mar 2026 18:15:21 +0000
Subject: [PATCH] Initial upload: shell-history-semantic-search v0.1.0

---
 README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 154 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0f90ab8..3361ccc 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,155 @@
-# shell-history-semantic-search
+# Shell History Semantic Search
 
-A privacy-first CLI tool for semantic shell history search using local embeddings
\ No newline at end of file
+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
+
+```bash
+pip install shell-history-search
+```
+
+Or install from source:
+
+```bash
+git clone <repository-url>
+cd shell-history-semantic-search
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# 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
+
+```bash
+# Index all shells
+shell-history-search index
+
+# Index specific shell only
+shell-history-search index --shell bash
+```
+
+### Search Command
+
+```bash
+# 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
+
+```bash
+shell-history-search stats
+```
+
+### Clear Command
+
+```bash
+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
+
+```bash
+# 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
\ No newline at end of file