Omniscient 🔍

Never forget a command again. Your complete CLI history, categorized and searchable.

Omniscient is a cross-platform command history tracker that captures every command you run, categorizes them intelligently, and makes them instantly searchable. Survive machine migrations, access your command library anywhere, and boost your CLI productivity.

Built with AI assistance. Verified by humans. Trusted through transparency.

📚 Complete Documentation | 📖 Full Index | 🤝 Contributing | 🔒 Security

Features

🚀 Zero Overhead: < 10ms command capture, won't slow you down
📊 Smart Categorization: Automatic categorization by command type
🔍 Fast Search: Find any command in milliseconds, even with 100k+ history
🔒 Privacy First: Automatic redaction of sensitive data
💾 Portable: Export/import your history, sync via Git
📈 Usage Analytics: Track your most-used commands
🎯 Simple: Single binary, minimal configuration
🐚 Multi-Shell: Supports Zsh and Bash (Fish coming soon)

Trust & Security

How can I trust an AI-built tool with my command history?

Valid question. Here's our answer:

Transparency First

✅ 100% Open Source: Every line of code is public and auditable
✅ No Network Calls: The binary contains zero networking code (no HTTP clients, no telemetry, no sockets) — your data never leaves your machine
✅ 91 Automated Tests: Comprehensive test coverage validates all functionality
✅ Zero Clippy Warnings: Strict linting enforced on every commit
✅ Security Audits: Automated cargo-audit checks on every push
✅ CI/CD Pipeline: All commits tested on Ubuntu & macOS before merge

Privacy Guarantees

# Verify yourself - no network calls anywhere in the codebase
grep -r "http" src/ --include="*.rs" | grep -v "^[[:space:]]*//"
# Returns nothing (except comments) - zero network activity

# All data stored locally
ls ~/.omniscient/
# history.db  config.toml  (that's it - no phoning home)

AI-Assisted Development

This project is built with AI assistance (Claude). Here's how we ensure quality:

Human Review: Every AI-generated line is reviewed and validated
Architecture Decisions: Humans make all design decisions (documented in ADRs)
Test Coverage: 91 tests written to validate AI-generated code
Incremental Development: Full git history shows human-guided, step-by-step progress

Verify Yourself

# Clone and audit the code
git clone https://github.com/daneb/omniscient
cd omniscient

# Run all tests
cargo test --verbose  # 91/91 passing

# Security audit
cargo install cargo-audit
cargo audit  # Zero vulnerabilities

# Read the architecture decisions
cat docs/adr/*.md

# Review test coverage
cargo tarpaulin --verbose

Bottom line: Trust through transparency. Don't trust us? Audit the code. That's why it's open source.

See SECURITY.md for our security policy and CONTRIBUTING.md for development transparency.

Quick Start

Installation

From Source (Recommended for v1.0.0)

# Clone the repository
git clone https://github.com/daneb/omniscient.git
cd omniscient

# Build and install
cargo install --path .

# Verify installation
omniscient --version

Via Cargo

cargo install omniscient

Setup

Zsh (Default)

# Initialize shell integration
omniscient init

# Add the output to your ~/.zshrc
omniscient init >> ~/.zshrc

# Reload your shell
source ~/.zshrc

Bash

Note: Bash requires the bash-preexec library.

# 1. Install bash-preexec
curl -sSL https://github.com/rcaloras/bash-preexec/raw/master/bash-preexec.sh -o ~/.bash-preexec.sh

# 2. Source bash-preexec in your profile
# For Linux (~/.bashrc):
echo 'source ~/.bash-preexec.sh' >> ~/.bashrc

# For macOS (~/.bash_profile):
echo 'source ~/.bash-preexec.sh' >> ~/.bash_profile

# 3. Add Omniscient hook
# For Linux:
omniscient init --shell bash >> ~/.bashrc

# For macOS:
omniscient init --shell bash >> ~/.bash_profile

# 4. Reload your shell
source ~/.bashrc  # Linux
source ~/.bash_profile  # macOS

That's it! Omniscient is now tracking your commands.

Usage

Basic Commands

# Search your command history
omniscient search "git commit"

# Show recent commands
omniscient recent 20

# Most frequently used commands
omniscient top 10

# Filter by category
omniscient category git

# View statistics
omniscient stats

Search Tips

Omniscient's search handles special characters seamlessly:

# Search for IP addresses
omniscient search "10.104.113.39"

# Search for URLs
omniscient search "https://api.github.com"
omniscient search "api.github.com"

# Search for file paths with dots
omniscient search "./config/settings.yaml"
omniscient search "../parent/file.txt"

# Search for email addresses
omniscient search "user@domain.com"

# Search for version numbers
omniscient search "v1.2.3"

# Search works with or without quotes
omniscient search 192.168.1.1
omniscient search "192.168.1.1"

Note: All searches use exact phrase matching, so searching for git commit will find commands containing that exact phrase, not commands with "git" OR "commit" separately.

Export & Sync

# Export your history
omniscient export history.json

# Import on a new machine
omniscient import history.json

# Sync via Git (recommended workflow)
omniscient export ~/.omniscient-backup/history.json
cd ~/.omniscient-backup
git add history.json
git commit -m "Update command history"
git push

Privacy & Redaction

Omniscient automatically redacts sensitive patterns. Configure in ~/.omniscient/config.toml:

[privacy]
redact_patterns = ["password", "token", "secret", "api_key"]
enabled = true

How It Works

Omniscient uses Zsh hooks to capture commands:

preexec: Starts a timer when you press Enter
Command executes: Your shell runs the command normally
precmd: Captures command, exit code, and duration
Storage: Saves to local SQLite database with categorization

Zero impact on your workflow, all happens in the background.

Example Output

$ omniscient search "docker"

[2025-11-10 14:32:45] [✓] docker ps -a                          (git/123)
[2025-11-10 12:15:30] [✗] docker build -t myapp .               (docker/45)
[2025-11-09 16:45:12] [✓] docker-compose up -d                  (docker/89)
[2025-11-09 10:22:01] [✓] docker logs -f container_name         (docker/12)

$ omniscient top 5

1. git status                    (1,234 uses)
2. ls -la                        (892 uses)
3. cd ..                         (654 uses)
4. git commit -m                 (432 uses)
5. cargo build                   (301 uses)

Configuration

Configuration file: ~/.omniscient/config.toml

[storage]
type = "sqlite"
path = "~/.omniscient/history.db"

[privacy]
redact_patterns = ["password", "token", "secret"]
enabled = true

[capture]
min_duration_ms = 0
max_history_size = 100000

Project Structure

~/.omniscient/
├── history.db      # SQLite database with your commands
└── config.toml     # Configuration file

Performance

Tested with 1,000+ commands:

Command capture: ~5ms (background, non-blocking)
Search queries: < 500ms
Stats calculation: < 500ms
Memory usage: < 50MB
Binary size: 5.2MB

Security

All data stored locally (~/.omniscient/)
File permissions: 600 (owner read/write only)
Automatic redaction of sensitive patterns
No telemetry, no cloud sync (unless you choose Git)

Roadmap

Version 1.0 (Current)

✅ Zsh integration
✅ SQLite storage
✅ Command categorization
✅ Search and retrieval
✅ Export/import

Future Versions

Bash, Fish, PowerShell support
Multi-line command handling
Command execution with safety checks
Web UI for history browsing
AI-powered command suggestions

Contributing

Contributions welcome! Please read our contributing guidelines first.

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Development

# Clone the repository
git clone https://github.com/daneb/omniscient.git
cd omniscient

# Build
cargo build

# Run tests
cargo test

# Install locally
cargo install --path .

Uninstallation

If you need to uninstall Omniscient:

Automated Uninstall (Recommended)

# Download and run the uninstall script
curl -sSL https://raw.githubusercontent.com/daneb/omniscient/master/uninstall.sh | bash

# Or if you have the repository cloned
./uninstall.sh

The script will:

Remove shell hooks from your ~/.zshrc
Remove the binary from ~/.cargo/bin/omniscient
Optionally delete your command history data
Create backups before deletion

Manual Uninstall

# 1. Remove shell hooks
# Edit ~/.zshrc and remove the "# Omniscient" section
vim ~/.zshrc

# 2. Remove the binary
cargo uninstall omniscient
# or manually
rm ~/.cargo/bin/omniscient

# 3. (Optional) Remove data directory
rm -rf ~/.omniscient

# 4. Reload shell
source ~/.zshrc

Note: The uninstaller creates backups before deletion. Your data will be backed up to ~/omniscient_backup_* before removal.

License

MIT License - see LICENSE for details.

FAQ

Q: Does this slow down my shell?
A: No. Capture happens asynchronously after command execution with < 10ms overhead.

Q: What about sensitive data in commands?
A: Automatic redaction of common patterns (passwords, tokens, etc.). Configurable.

Q: Can I use this across multiple machines?
A: Yes! Export your history to JSON and sync via Git or any file sync tool.

Q: Does it capture command output?
A: No, only the command itself and metadata (exit code, duration, etc.). Keeps storage lean.

Q: What if I delete my machine?
A: Export regularly and keep the JSON in version control. Import on your new machine.

Q: Is my data sent anywhere?
A: Never. Everything is local unless you explicitly export and sync via Git.

Acknowledgments

Built with Rust 🦀 for performance and reliability.

Inspired by the need to never lose a useful command again.

Project Status

Version: 1.0.0 Status: ✅ Production Ready Maintained: Yes Automated Tests: 91 passing Code Quality: Zero warnings, all clippy lints passed

omniscient 1.2.6