Initial upload: shell-history-semantic-search v0.1.0

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
+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