Metadata-Version: 2.4
Name: whatwasit
Version: 0.2.0
Summary: Local-first semantic search for your shell history. Search by intent, not exact text. No cloud, no API keys.
Project-URL: Homepage, https://github.com/ThorOdinson246/whatwasit
Project-URL: Repository, https://github.com/ThorOdinson246/whatwasit
Project-URL: Issues, https://github.com/ThorOdinson246/whatwasit/issues
Author-email: ThorOdinson246 <110178596+ThorOdinson246@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 ThorOdinson246
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,embeddings,history,local-first,privacy,semantic-search,shell,shell-history,whatwasit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: numpy>=1.24
Requires-Dist: onnxruntime>=1.17
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.40
Requires-Dist: tokenizers>=0.15
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: usearch>=2.12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# whatwasit

**Local-first semantic search for your shell history.**

Search by what you were *trying to do*, not the exact command you typed — and
nothing ever leaves your machine.

```bash
whatwasit "how did I fix that nginx issue"
```

Returns the session of commands you actually ran (`cd`, `vim`, `systemctl reload
nginx`) weeks ago, even though you never typed "fix" or "issue".

## Features

- **Intent-based recall** — searches whole command sessions, not isolated lines
- **Hybrid search** — semantic embeddings plus FTS5 keyword matching for tool
  names, flags, and short literal queries
- **Incremental indexing** — `whatwasit index` skips rebuild when history files
  are unchanged (mtime/size fingerprint)
- **Interactive TUI** — live debounced search, collapsible sessions, themes
- **Scripting** — `--json`, `--plain`, and pipe-friendly headless output
- **Fully offline** — ONNX embedding model on CPU; no cloud, no API keys
- **Non-destructive** — reads your existing history files; never modifies them

## Install

```bash
pip install whatwasit
```

Upgrade an existing install:

```bash
pip install -U whatwasit
```

**Requirements:** Python 3.9+, ~100 MB for the embedding model (downloaded once on
first run), and for clipboard copy on Linux: `wl-copy` (Wayland) or `xclip`
(X11).

## Quick start

```bash
# Build the search index from your shell history
whatwasit index

# Interactive REPL (default when run with no arguments)
whatwasit

# One-shot search
whatwasit "that time I set up passwordless ssh"

# JSON for scripts and agents
whatwasit "docker compose down" --json
```

## Usage

```bash
# Refresh the index (skips if history sources unchanged)
whatwasit index

# Force a full rebuild
whatwasit index --rebuild

# Adjust session grouping window (default: 300 seconds)
whatwasit index --window 600

# Plain output (Rich panels on a TTY, line-oriented when piped)
whatwasit "docker volume that wouldn't persist" --plain

# Machine-readable JSON
whatwasit "nginx config" --json

# Return more results
whatwasit "nginx config" -k 20

# Optional warm daemon for faster repeated queries
whatwasit daemon start
whatwasit daemon status
whatwasit daemon stop
```

### TUI / REPL

Running `whatwasit` with no arguments opens a persistent REPL: search bar on top,
results below, key hints in the footer. Results update live as you type (short
debounce). Each row shows the primary command in bold, path underneath, and a
relative timestamp (`2h ago`) right-aligned. Low-confidence matches show a `⚠`
after the command.

Sessions with multiple commands collapse to the matched command plus context;
press **Space** to expand. When the top result is below the confidence threshold
(default 0.40), a soft warning banner appears without hiding results.

| Key / command | Action |
|---------------|--------|
| Type in search box | Live search (2+ characters) |
| `j` / `k` or arrows | Navigate results |
| Enter | Copy matched command(s) to clipboard |
| Space | Expand or collapse a session |
| `m` or `/more` | Show more results |
| `t` or `/theme` | Cycle color theme |
| `/theme <name>` | Set theme (`midnight`, `default`, `high-contrast`) |
| `/settings` | Show theme and config |
| `/help` | Show keybindings |
| Tab / Shift+Tab | Focus results ↔ search |
| `/quit` or `q` | Quit |

One-shot `whatwasit "query"` opens the same result browser with pre-fetched
results. Use `--plain`, `--headless`, or `--json` for non-interactive output.

### Configuration

Optional config file: `~/.config/whatwasit/config.toml`

```toml
output_mode = "tui"              # "tui" or "plain"
tui_page_size = 5
tui_theme = "midnight"           # midnight | default | high-contrast
low_confidence_threshold = 0.40
use_daemon = true                # use warm daemon when running (if started)
```

Theme changes from the REPL (`t` or `/theme`) are saved here automatically.
CLI flags override config values where applicable (for example, `--plain` forces
plain output).

**Data directory:** `~/.local/share/whatwasit/` (`whatwasit.db` + `index.usearch`)

If you indexed under the older `hist` app name, that data path is still detected
automatically — no re-index required.

**History sources:** `~/.zsh_history`, `~/.bash_history`, and Atuin (if installed).
All sources are read non-destructively.

## How it works

1. **Parse** — reads shell history into timestamped commands
2. **Group** — clusters commands into sessions by time gap and working directory
3. **Embed** — encodes each session locally with
   [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
   (~22 MB ONNX, CPU-only)
4. **Index** — stores vectors in a local index, session metadata in SQLite, and
   command text in FTS5 for keyword search
5. **Search** — embeds your query, finds nearest sessions, merges keyword hits
   via reciprocal-rank fusion, and highlights matching commands within each session

## Privacy

- All search and indexing run on your machine
- No network calls after the one-time model download
- Your shell history is never uploaded anywhere
- Daemon Unix socket is restricted to your user (`0o600`)

## Feedback

Bug reports and feature requests:
[github.com/ThorOdinson246/whatwasit/issues](https://github.com/ThorOdinson246/whatwasit/issues)

## License

MIT — see [LICENSE](LICENSE).
