icommand-cli 0.1.0__tar.gz

icommand_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

icommand_cli-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: icommand-cli
+Version: 0.1.0
+Summary: AI-powered terminal command history search
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: toml>=0.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.16
+Requires-Dist: tokenizers>=0.15
+Requires-Dist: huggingface-hub>=0.20
+Requires-Dist: textual>=0.50
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: faiss-cpu>=1.7.4
+Dynamic: license-file
+
+# iCommand
+
+`iCommand` is a local-first command history search tool for people who spend a lot of time in the terminal and want better recall than shell history alone.
+
+It captures commands from your shell, stores them locally, and lets you search them through a full-screen TUI or a quick CLI command. Literal keyword lookups are supported, and recent history can also be searched semantically using local embeddings.
+
+## Why It Exists
+
+Traditional shell history is fast, but it is not great at answering questions like:
+
+- "What was that `pipx` command I ran last week?"
+- "How did I activate that virtualenv?"
+- "What did I use to reinstall this tool?"
+
+`iCommand` is built to make those lookups easier without turning your history into a cloud product.
+
+## Current Status
+
+This project is usable today, but it is still early.
+
+- Local embeddings are implemented with Snowflake Arctic Embed XS via ONNX.
+- The TUI and CLI search flows are implemented.
+- Keyword search is backed by SQLite FTS.
+- Local storage is bounded so the app does not grow forever.
+- `ask` / conversational search is not implemented yet.
+- Only the `local` embedding provider is implemented right now. `openai`, `anthropic`, and `ollama` are present as future placeholders.
+
+## Features
+
+- Full-screen terminal UI for browsing and searching command history
+- CLI search for quick one-off lookups
+- Exact and prefix keyword matching for literal shell queries
+- Semantic search for recent history using local embeddings
+- Shell history import for existing Bash and Zsh users
+- Automatic local storage limits with pruning of oldest history
+- Semantic indexing limited to a recent hot window to keep disk usage bounded
+
+## Installation
+
+### Prerequisites
+
+- Python `3.9+`
+- `pipx`
+- Bash or Zsh
+- Internet access on first semantic-search use to download the ONNX embedding model from Hugging Face
+
+### Install From GitHub
+
+```bash
+pipx install 'git+https://github.com/carnifex-cmd/iCommand.git'
+```
+
+Initialize the app and install the shell hook:
+
+```bash
+icommand init
+```
+
+Then open a new terminal, or reload your shell config.
+
+## Quick Start
+
+Open the TUI:
+
+```bash
+ic
+```
+
+Run a quick CLI search:
+
+```bash
+icommand search "reinstall"
+```
+
+Import recent shell history:
+
+```bash
+icommand import-history
+```
+
+Inspect current settings:
+
+```bash
+icommand config
+```
+
+Uninstall the app:
+
+```bash
+icommand uninstall
+```
+
+## Commands
+
+### `icommand init`
+
+Initializes the local database, writes a default config file, appends the shell hook to `~/.bashrc` and `~/.zshrc`, and performs an initial sync so search works immediately.
+
+### `icommand tui`
+
+Launches the full-screen Textual TUI.
+
+The shell hook also defines:
+
+```bash
+alias ic='icommand tui'
+```
+
+### `icommand search "<query>"`
+
+Runs a CLI search against your local history.
+
+### `icommand import-history`
+
+Imports commands from `~/.zsh_history` or `~/.bash_history`.
+
+Useful options:
+
+```bash
+icommand import-history --limit 5000
+icommand import-history --file ~/.zsh_history
+```
+
+### `icommand config`
+
+Shows or updates config values.
+
+Examples:
+
+```bash
+icommand config
+icommand config max_results 10
+icommand config tui_max_results 5
+icommand config storage_soft_limit_mb 1024
+```
+
+### `icommand uninstall`
+
+Removes local app data, shell hook lines, and attempts to uninstall the binary.
+
+## How It Works
+
+1. A shell hook captures commands from Bash or Zsh.
+2. Commands are stored in a local SQLite database under `~/.icommand/history.db`.
+3. SQLite FTS is used for keyword search.
+4. Recent commands can also be embedded locally and indexed in FAISS for semantic search.
+5. A storage maintenance pass keeps disk growth bounded by pruning the oldest history and limiting semantic indexing to a recent hot window.
+
+## Configuration
+
+Default config lives at `~/.icommand/config.toml`.
+
+Important settings:
+
+```toml
+provider = "local"
+max_results = 10
+tui_max_results = 5
+storage_soft_limit_mb = 1024
+storage_hard_limit_mb = 2048
+live_command_limit = 1000000
+semantic_command_limit = 250000
+```
+
+What they mean:
+
+- `provider`: embedding backend. Only `local` works today.
+- `max_results`: maximum results returned by CLI search.
+- `tui_max_results`: maximum visible results in the TUI.
+- `storage_soft_limit_mb`: target cap for local app data under `~/.icommand`.
+- `storage_hard_limit_mb`: emergency cap after which new embedding work pauses until storage is reduced.
+- `live_command_limit`: total retained commands kept locally.
+- `semantic_command_limit`: number of newest commands eligible for semantic indexing.
+
+## Privacy and Local Data
+
+By default, `iCommand` is local-first.
+
+It stores:
+
+- command text
+- working directory
+- timestamp
+- exit code when available
+- local embeddings for semantically indexed commands
+- a local FAISS index and metadata
+
+Primary storage locations:
+
+- `~/.icommand/history.db`
+- `~/.icommand/vectors.faiss`
+- `~/.icommand/vectors_metadata.pkl`
+
+The local embedding model is downloaded and cached separately by Hugging Face tooling, typically under:
+
+- `~/.cache/huggingface/hub`
+
+## Development
+
+Clone the repo and install it locally with `pipx`:
+
+```bash
+git clone https://github.com/carnifex-cmd/iCommand.git
+cd iCommand
+pipx install --force --editable .
+```
+
+Useful local commands:
+
+```bash
+icommand init
+icommand config
+ic
+```
+
+If you are working from source and want the installed binary to use your local edits, prefer the editable `pipx` install above instead of reinstalling directly from the GitHub URL.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+When contributing:
+
+- keep behavior local-first
+- avoid unbounded disk or memory growth
+- preserve fast literal shell lookup behavior
+- document user-visible limitations honestly
+
+## Roadmap
+
+Likely next areas of work:
+
+- better live-search freshness while the TUI stays open
+- finishing additional embedding providers
+- conversational command recall
+- stronger uninstall cleanup
+- tests and release automation
+
+## License
+
+Intended license: `MIT`.
+
+If you publish this repository, add a matching `LICENSE` file so the legal terms are explicit in the repo itself.

icommand_cli-0.1.0/README.md

@@ -0,0 +1,243 @@
+# iCommand
+
+`iCommand` is a local-first command history search tool for people who spend a lot of time in the terminal and want better recall than shell history alone.
+
+It captures commands from your shell, stores them locally, and lets you search them through a full-screen TUI or a quick CLI command. Literal keyword lookups are supported, and recent history can also be searched semantically using local embeddings.
+
+## Why It Exists
+
+Traditional shell history is fast, but it is not great at answering questions like:
+
+- "What was that `pipx` command I ran last week?"
+- "How did I activate that virtualenv?"
+- "What did I use to reinstall this tool?"
+
+`iCommand` is built to make those lookups easier without turning your history into a cloud product.
+
+## Current Status
+
+This project is usable today, but it is still early.
+
+- Local embeddings are implemented with Snowflake Arctic Embed XS via ONNX.
+- The TUI and CLI search flows are implemented.
+- Keyword search is backed by SQLite FTS.
+- Local storage is bounded so the app does not grow forever.
+- `ask` / conversational search is not implemented yet.
+- Only the `local` embedding provider is implemented right now. `openai`, `anthropic`, and `ollama` are present as future placeholders.
+
+## Features
+
+- Full-screen terminal UI for browsing and searching command history
+- CLI search for quick one-off lookups
+- Exact and prefix keyword matching for literal shell queries
+- Semantic search for recent history using local embeddings
+- Shell history import for existing Bash and Zsh users
+- Automatic local storage limits with pruning of oldest history
+- Semantic indexing limited to a recent hot window to keep disk usage bounded
+
+## Installation
+
+### Prerequisites
+
+- Python `3.9+`
+- `pipx`
+- Bash or Zsh
+- Internet access on first semantic-search use to download the ONNX embedding model from Hugging Face
+
+### Install From GitHub
+
+```bash
+pipx install 'git+https://github.com/carnifex-cmd/iCommand.git'
+```
+
+Initialize the app and install the shell hook:
+
+```bash
+icommand init
+```
+
+Then open a new terminal, or reload your shell config.
+
+## Quick Start
+
+Open the TUI:
+
+```bash
+ic
+```
+
+Run a quick CLI search:
+
+```bash
+icommand search "reinstall"
+```
+
+Import recent shell history:
+
+```bash
+icommand import-history
+```
+
+Inspect current settings:
+
+```bash
+icommand config
+```
+
+Uninstall the app:
+
+```bash
+icommand uninstall
+```
+
+## Commands
+
+### `icommand init`
+
+Initializes the local database, writes a default config file, appends the shell hook to `~/.bashrc` and `~/.zshrc`, and performs an initial sync so search works immediately.
+
+### `icommand tui`
+
+Launches the full-screen Textual TUI.
+
+The shell hook also defines:
+
+```bash
+alias ic='icommand tui'
+```
+
+### `icommand search "<query>"`
+
+Runs a CLI search against your local history.
+
+### `icommand import-history`
+
+Imports commands from `~/.zsh_history` or `~/.bash_history`.
+
+Useful options:
+
+```bash
+icommand import-history --limit 5000
+icommand import-history --file ~/.zsh_history
+```
+
+### `icommand config`
+
+Shows or updates config values.
+
+Examples:
+
+```bash
+icommand config
+icommand config max_results 10
+icommand config tui_max_results 5
+icommand config storage_soft_limit_mb 1024
+```
+
+### `icommand uninstall`
+
+Removes local app data, shell hook lines, and attempts to uninstall the binary.
+
+## How It Works
+
+1. A shell hook captures commands from Bash or Zsh.
+2. Commands are stored in a local SQLite database under `~/.icommand/history.db`.
+3. SQLite FTS is used for keyword search.
+4. Recent commands can also be embedded locally and indexed in FAISS for semantic search.
+5. A storage maintenance pass keeps disk growth bounded by pruning the oldest history and limiting semantic indexing to a recent hot window.
+
+## Configuration
+
+Default config lives at `~/.icommand/config.toml`.
+
+Important settings:
+
+```toml
+provider = "local"
+max_results = 10
+tui_max_results = 5
+storage_soft_limit_mb = 1024
+storage_hard_limit_mb = 2048
+live_command_limit = 1000000
+semantic_command_limit = 250000
+```
+
+What they mean:
+
+- `provider`: embedding backend. Only `local` works today.
+- `max_results`: maximum results returned by CLI search.
+- `tui_max_results`: maximum visible results in the TUI.
+- `storage_soft_limit_mb`: target cap for local app data under `~/.icommand`.
+- `storage_hard_limit_mb`: emergency cap after which new embedding work pauses until storage is reduced.
+- `live_command_limit`: total retained commands kept locally.
+- `semantic_command_limit`: number of newest commands eligible for semantic indexing.
+
+## Privacy and Local Data
+
+By default, `iCommand` is local-first.
+
+It stores:
+
+- command text
+- working directory
+- timestamp
+- exit code when available
+- local embeddings for semantically indexed commands
+- a local FAISS index and metadata
+
+Primary storage locations:
+
+- `~/.icommand/history.db`
+- `~/.icommand/vectors.faiss`
+- `~/.icommand/vectors_metadata.pkl`
+
+The local embedding model is downloaded and cached separately by Hugging Face tooling, typically under:
+
+- `~/.cache/huggingface/hub`
+
+## Development
+
+Clone the repo and install it locally with `pipx`:
+
+```bash
+git clone https://github.com/carnifex-cmd/iCommand.git
+cd iCommand
+pipx install --force --editable .
+```
+
+Useful local commands:
+
+```bash
+icommand init
+icommand config
+ic
+```
+
+If you are working from source and want the installed binary to use your local edits, prefer the editable `pipx` install above instead of reinstalling directly from the GitHub URL.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+When contributing:
+
+- keep behavior local-first
+- avoid unbounded disk or memory growth
+- preserve fast literal shell lookup behavior
+- document user-visible limitations honestly
+
+## Roadmap
+
+Likely next areas of work:
+
+- better live-search freshness while the TUI stays open
+- finishing additional embedding providers
+- conversational command recall
+- stronger uninstall cleanup
+- tests and release automation
+
+## License
+
+Intended license: `MIT`.
+
+If you publish this repository, add a matching `LICENSE` file so the legal terms are explicit in the repo itself.

icommand_cli-0.1.0/icommand/__init__.py

@@ -0,0 +1 @@
+# icommand — AI-powered terminal command history search

icommand_cli-0.1.0/icommand/capture.py

@@ -0,0 +1,30 @@
+"""Command capture for icommand.
+
+Thin wrapper around db.insert_command() for use by the shell hook.
+Can be invoked directly: python -m icommand.capture <command> <directory>
+"""
+
+import sys
+from typing import Optional
+
+from icommand.db import init_db, insert_command
+
+
+def capture_command(command: str, directory: str, exit_code: Optional[int] = None) -> None:
+    """Capture a single command and store it in the database.
+
+    Args:
+        command: The shell command that was executed.
+        directory: The working directory when the command was run.
+        exit_code: The exit code of the command (optional).
+    """
+    init_db()
+    insert_command(command, directory, exit_code)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print("Usage: python -m icommand.capture <command> <directory>", file=sys.stderr)
+        sys.exit(1)
+
+    capture_command(sys.argv[1], sys.argv[2])