Seekr is an AI-powered file search tool for Linux that understands natural language. Instead of wrestling with find or locate commands, just type what you're looking for — the way you'd say it out loud.
"python files from yesterday"
"report pdf in downloads"
"that parser file I edited in GigArmor"
Seekr parses your intent using a hybrid rule-based + AI pipeline (powered by Groq), queries a local SQLite FTS5 index for near-instant results, and opens the file's location in your file manager with one click.
It ships with both a sleek GTK4/Adwaita GUI (GNOME-native) and a CLI for power users.
| Feature | Description |
|---|---|
| AI Query Parsing | Understands natural language via Groq LLM; extracts filename keywords, folder hints, and structured filters |
| Fast Indexed Search | SQLite FTS5 full-text search index — no slow find traversals on every query |
| Smart Sync Indexer | Background indexer that adds new files, updates changed ones, and prunes deleted ones — without a full rebuild |
| Filter Support | Filter by file extension, time range (today, yesterday, last week, custom), folder name, and file size |
| Size-Based Search | Find the largest/smallest files or filter by size thresholds — e.g. "largest files in downloads", "files over 10MB" |
| Secure API Key Storage | Groq API key stored using the system keyring (no plaintext secrets on disk) |
| GNOME-Native GTK4 UI | Built with Adwaita for a native GNOME look and feel |
| One-Click Open | Double-click a result to reveal the file in your file manager (via DBus ShowItems) |
The easiest and recommended way to install Seekr on Fedora/RHEL-based systems.
# Enable the COPR repository
sudo dnf copr enable a-anuj/seekr
# Install Seekr
sudo dnf install seekrSupported: Fedora 39+, RHEL 9+, and compatible derivatives.
Search for Seekr in your application menu, or run:
seekrOn first launch, Seekr will prompt you to enter your Groq API Key. This enables the AI query understanding features.
- Get a free API key at console.groq.com
- Paste it in the setup screen (keys start with
gsk_) - Click Save & Continue — your key is stored securely in the system keyring
Seekr will then start indexing your files in the background.
Seekr uses a three-stage pipeline for every query:
User Query
│
▼
┌─────────────────────────────────┐
│ Stage 1: Rule-Based Parser │ ← Extracts extension, time keywords (fast, zero-cost)
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Stage 2: AI Name & Folder │ ← Groq LLM extracts filename keyword & folder hint
│ Extractor │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Stage 3: Confidence Router │ ← Scores filter set; calls full AI parser if weak
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ SQLite FTS5 Index Search │ ← Near-instant full-text search on local DB
└─────────────────────────────────┘
│
▼
Results (sorted by most recent)
Seekr uses a high-performance, event-driven architecture to ensure your index is always live without draining system resources.
At startup, a background thread runs the smart indexer:
- Scans
~/Projects,~/Desktop,~/Downloads,~/Documents,~/Music,~/Videos,~/Pictures - Skips
.git,node_modules,__pycache__,.venv,.cache, etc. - Uses mtime comparison and inotify to instantly keep files in sync
- Stores file size for size-based filtering and sorting
- Removes entries for files that were deleted from disk
- Stores metadata in
~/.local/share/seekr/seekr.db(SQLite FTS5)
seekr/
├── app/
│ ├── ai/
│ │ ├── name_extractor.py # AI: extracts filename keyword from query
│ │ ├── folder_extractor.py # AI: extracts folder hint from query
│ │ ├── parser_ai.py # AI: full structured JSON filter extraction (fallback)
│ │ └── utils.py # Converts AI JSON output → internal filter dict
│ ├── app_entry/
│ │ ├── main_gtk.py # GTK4/Adwaita GUI (primary UI)
│ │ └── main.py # PyQt6 GUI (legacy/alternate UI)
│ ├── cli/
│ │ └── main.py # CLI entry point (`seekr` command)
│ ├── core/
│ │ ├── parser.py # Rule-based query parser (extension, time)
│ │ ├── router.py # Hybrid routing: rule-based → AI → fallback
│ │ ├── search.py # Direct filesystem search (fallback, no DB)
│ │ ├── indexer.py # Smart background file indexer
│ │ └── filters.py # Filter helper utilities
│ └── storage/
│ ├── db.py # SQLite FTS5 DB init & search
│ └── check_db.py # Dev utility: preview indexed DB contents
├── assets/
│ └── logo.png # Application icon
└── install.sh # Manual install script (non-COPR)
| Query | What Seekr Understands |
|---|---|
"report" |
Files with "report" in the name |
"python files today" |
.py files modified today |
"tar file yesterday" |
.tar files from yesterday |
"pdf in downloads" |
.pdf files inside the Downloads folder |
"parser file in GigArmor" |
File named "parser" inside a "GigArmor" folder |
"python files last week" |
.py files from last week (AI parses date range) |
"pictures" |
All files inside ~/Pictures, sorted by most recent |
"largest files in pictures" |
Files from ~/Pictures sorted by size (largest first) |
"files over 10MB" |
Any indexed file larger than 10 MB |
"smallest python files" |
.py files sorted by size (smallest first) |
- OS: Linux (Fedora 39+ recommended; Debian/Ubuntu supported via manual install)
- Python: 3.10+
- Desktop: GNOME with GTK 4.0 + Adwaita (for GUI; CLI works anywhere)
- Dependencies:
python3-gobject,gtk4,libadwaita,keyring,groq,python-dotenv - Optional:
locate/plocate(used by the CLI fast-search fallback)
Seekr uses Groq for its AI query understanding. A free-tier account is sufficient.
- GUI: Enter your key on the first-launch setup screen. It is stored securely via the system keyring.
- CLI / Manual: Create a
.envfile in the project root:
GROQ_API_KEY=gsk_your_key_here
⚠️ Never commit your.envfile. It is already in.gitignore.
Seekr is continuously built and deployed to Fedora COPR using GitHub Actions.
If you prefer to install from source:
git clone https://github.com/a-anuj/seekr.git
cd seekr
chmod +x install.sh
./install.shThe script will:
- Check and install GTK system dependencies (
python3-gobject,gtk4) - Install Python dependencies via
pip
You can start the app by typing seekr to the terminal.
Tip
Better Usage: For the best experience, add a Custom Keyboard Shortcut in your system settings (e.g., Super + Shift + F or Ctrl + Space) set to the command seekr. This lets you summon the search window instantly from anywhere!
Contributions are welcome! Feel free to open issues or pull requests.
This project is licensed under the MIT License.