Hister: Search Local Files Instantly in Linux

We’ve all been there. You know a markdown note, PDF, or config file contains the information you need, but you can’t remember where you saved it. The find command only works if you know the filename, while grep -r has to scan every directory, which can be slow on large folders.

Hister solves this by creating an index of your files in advance. Instead of scanning everything every time you search, it looks up the indexed data, so searches that normally take several seconds can return results in just a few milliseconds.

It was tested on Ubuntu 26.04 and RHEL 10, but since Hister is distributed as a single Go binary, it works the same way on most modern Linux distributions.

What Hister Actually Does

Hister runs a small local server on your system and builds a searchable index of the folders you choose. Instead of searching every file each time you run a query, it searches the index it has already created, making searches much faster.

It can read content from PDF, DOCX, Markdown (.md), Org (.org), and plain text files, then stores the extracted text in its index. This lets you search by file content, title, file type, or file path, even if you don’t remember the filename.

Hister can also index your browser history and web pages with the help of a companion browser extension, but in this guide we’ll focus only on searching local files.

Installing Hister

Download the latest Hister binary for your Linux system from the GitHub releases page. At the time of writing, the latest stable release is v0.16.0.

After downloading it, make the binary executable and move it to a directory that’s included in your PATH:

chmod +x hister
sudo mv hister /usr/local/bin/hister

The chmod +x command gives the binary permission to run as a program. By default, downloaded files usually don’t have the executable permission set.

The sudo mv command moves the binary to/usr/local/bin/, which is a standard location for user-installed programs. Since this directory is already in yourPATH, you can run hister from any location without specifying its full path.

The sudo command is required because writing to /usr/local/bin/ needs administrator privileges. Without it, the move operation will fail with a Permission denied error.

Starting the Hister Server

Hister uses the same command-line tool to run its local server. Start it with:

hister listen

By default, the server listens on 127.0.0.1:4433, which means it’s only accessible from the same computer.

Keep the terminal window open while the server is running. If you close the terminal, the Hister server stops. If you want it to keep running while you use the same terminal for other tasks, you can start it inside a terminal multiplexer such as tmux or screen.

Once the server is running, open your web browser and visit:

http://localhost:4433

This opens Hister’s web interface, where you can search your indexed files using a simple browser-based search page.

Telling Hister Which Files to Index

Hister only indexes the folders you specify in its configuration file. By default, it looks for the configuration at:

~/.config/hister/config.yml

If the file doesn’t exist, create it with:

hister create-config ~/.config/hister/config.yml

Open the configuration file in your preferred text editor:

nano ~/.config/hister/config.yml

Locate the existing indexer: section and replace the directories: [] entry with the following configuration. Replace /home/username/Documents with the folder you want Hister to index.

indexer:
  detect_languages: true
  directories:
    - path: /home/username/Documents
      filetypes:
        - md
        - txt
        - pdf
      excludes:
        - "*secret*"
        - "*.tmp"
  max_file_size_mb: 1

The path option specifies the directory that Hister should index.

The filetypes option limits indexing to the listed file extensions. In this example, only Markdown (.md), text (.txt), and PDF (.pdf) files are indexed.

The excludes option skips files that match the specified patterns. Here, files with secret in their name and temporary files ending in .tmp are ignored.

After saving the file, restart the server to load the updated configuration:

hister listen

Hister immediately begins indexing the selected folder in the background, so you can start using the server without waiting for the entire indexing process to finish. After the initial scan, it automatically watches the folder for changes and updates the index whenever files are added, modified, or deleted.

Searching Your Indexed Files

Once the Hister server is running and your files have been indexed, open a new terminal window or tab and run:

hister search

Running hister search without any search terms launches Hister’s built-in terminal interface (TUI). As you type, matching files appear instantly.

Use these keyboard shortcuts to navigate the interface:

• Tab – Switch between the search box and the results list.
• Enter – Open the selected file.
• Ctrl+D – Remove the selected entry from the index.

If you prefer a graphical interface, open your web browser and visit:

http://localhost:4433

The web interface lets you search your indexed files from a browser instead of the terminal.

A Few Things That Trip People Up

By default, Hister only indexes files up to 1 MB in size. This limit is controlled by the indexer.max_file_size_mb setting in the configuration file. If a large PDF or DOCX file doesn’t appear in your search results, increase this value and restart the server so Hister can index the file.

Hister also skips hidden files and folders by default, along with common directories such as node_modules and __pycache__. If you want to include hidden files, add the include_hidden: true option to the directory entry in your configuration file.

For Example:

indexer:
  detect_languages: true
  directories:
    - path: /home/username/Documents
      include_hidden: true
      filetypes:
        - md
        - txt
        - pdf

After making any changes to the configuration file, restart the Hister server for the new settings to take effect.

Searching with Hister’s Query Language

After your files have been indexed, you can start searching them from the terminal by running:

hister search

Simply type a word or phrase into the search box. For example, searching for invoice returns any indexed file that contains that word in its title, content, or file path.

If you need more precise results, Hister supports field-specific searches.

• title: searches only file or page titles.
• text: searches only the contents of files.
• url: searches file paths or URLs.
• type:file searches only local files.
• type:web searches only indexed web pages.
• Prefix a term with - to exclude it from the results.

For example, to find invoices that aren’t drafts, type:

invoice -draft

You can also combine multiple search filters, use quotation marks for exact phrases, use * as a wildcard, and group search terms with parentheses and | for OR conditions.
For example:

title:(invoice|receipt) type:file -"draft"

This query searches for local files whose title contains either invoice or receipt, while excluding any results that contain the exact word draft.

Searches are case-insensitive, so searching for Invoice, invoice, or INVOICE produces the same results.

Exporting and Backing Up Your Index

If you’ve spent time building your index, it’s a good idea to back it up. Hister lets you export the indexed data to a file with:

hister export backup.json

This creates a backup named backup.json containing your indexed data. You can keep this file as a backup or copy it to another system.

To restore the backup later, use:

hister import file backup.json

This imports the contents of the backup file into Hister, allowing you to restore a previously exported index.

In addition to JSON export files, hister import file can also import saved HTML pages and 7z archives created from previous exports. You can even specify a directory, and Hister imports all supported files inside it in filename order.

Common Mistakes

Forgetting to Restart After Changing the Configuration:- Hister automatically detects new, modified, and deleted files inside directories that are already being indexed. However, if you add a new directory to config.yml, you must restart the Hister server before it starts indexing that location.

If the files in a newly added folder don’t appear in your search results, restart the server:

hister listen

Once the server restarts, Hister begins indexing the new directory in the background.

Leaving the Server Running in the Foreground:- Many new users leave a terminal window open just to keep hister listen running. While this works, it’s not the only option.

If you don’t want to keep a terminal dedicated to Hister, you can run it inside a terminal multiplexer such as tmux or screen. For a more permanent setup, you can also configure Hister to run as a systemd user service, allowing it to start automatically and continue running in the background after you log in.