searchi/README.md

<p align="center">
  <img src="assets/brand/searchi-app.png" alt="searchi app icon" width="96">
</p>

<h1 align="center">searchi</h1>
<p align="center"><strong>Find what matters. Locally.</strong></p>
<p align="center">Your documents, code, photos, music and movies. One place to search.</p>

You remember what was in the file. searchi helps you find it—even when you
don't remember what it was called.

Search a filename, a phrase, or describe what you're looking for in your own
words. See the relevant passage or media preview alongside your results,
then open the file. Your files stay on your device.

![searchi finding a supplier agreement and highlighting its matching passage](docs/screenshots/search-light.png)

*“cancel the supplier partnership” finds the agreement and brings its
termination passage into view.*

## Find it your way

| What you remember | What to try |
| --- | --- |
| The file's name | `Supplier agreement.pdf` |
| Words inside a document | `sixty days written notice` |
| What a document is about | `cancel the supplier partnership` |
| What a piece of code does | `retry failed requests with exponential backoff` |
| An exact code symbol | `refreshAccessToken` |
| A photo's subject | `mountains reflected in calm water` |
| An artist or song title | `Nina Simone` or `Feeling Good`, if present in your music tags |
| A scene or sound | Try `rain and thunder` or `a boat crossing a lake` in experimental media search |

**Names, words and meaning work together.** Exact filenames help you get
straight to a known file. Content search finds the words inside it. Google
EmbeddingGemma 2 adds local semantic search for related meaning, images and
sound.

Use **All files** to narrow results by folder, file extension, modification
date, file size or media duration. Choose a result to inspect it before opening.

Windows 0.1.5 offers **Artist (exact)** and **Track title (exact)**
filters for music. Enter the complete tag, with or without a text query. These
filters ignore letter case and surrounding spaces; files without the matching
music tag stay out of the results. Existing indexes need a media indexing pass
before these new filters can use their tags. Windows 0.1.5 includes these filters; older downloads need an update.

### Windows 0.1.6: search spoken passages

Windows 0.1.6 adds experimental local speech recognition for audio
and video. Describe a spoken topic, inspect the recognized passage, and jump
to its estimated position. Google EmbeddingGemma 2 remains the search model;
the additional speech models help turn spoken words into searchable passages.
For example, try `someone talking about equal rights` in a recording that
contains that topic. Download Windows 0.1.6 below to use it.

### Find the implementation

Choose **Code** in the **All files** filters to search source files. Look up a
symbol you know, or describe the behavior you need. Local Google embeddings
help connect your description to an implementation; the preview preserves code
formatting and shows the source passage's starting line.

Rust, Python, JavaScript/TypeScript, C/C++, Go, Java, C#, Swift, SQL and many
other source formats are supported, including named build files such as
`Makefile` and `Dockerfile`. Add your project folder and let semantic indexing
finish for meaning-based search. See [code search](docs/CODE-SEARCH.md) for
details and agent integration.

## A little less searching. A little more finding.

Matching words stand out in the results and document preview. PDF results
retain their page number; text results show the relevant passage. If you'd
like an explanation, expand the small **Why this result?** detail.

![searchi's dark theme with search results and a document passage](docs/screenshots/search-dark.png)

Light and dark themes follow your system preference. Keyboard navigation,
short transitions and reduced-motion support keep the interface familiar
and comfortable. In **Settings → Appearance**, choose a solid, glass or
frosted-glass window background and adjust its tint. Reading surfaces stay
clear. Native glass currently requires **Windows 11 22H2 or later**. macOS,
Linux, unsupported Windows versions and high-contrast mode currently use a
solid background; your appearance preference is retained.

![searchi finding and previewing a mountain lake photograph](docs/screenshots/media-search.png)

*“mountains reflected in calm water” searches the pictures themselves,
so a useful filename isn't required.*

Images open in the preview. Audio and video have playback controls, and
matching media segments can jump to their approximate location. Nothing
autoplays when you select a result.

## Get searchi

**Windows x64 version 0.1.6 is available.**

- [Download the Windows installer](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.6/searchi_0.1.6_x64-setup.exe) — about 100 MB.
- [Checksums](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.6/searchi_0.1.6_x64-setup.exe.sha256) · [Release notes](https://tea.karlcom.de/karl/searchi/releases/tag/v0.1.6).

Already installed? Close searchi before installing the update. Version 0.1.6 adds experimental local speech search, exact music artist/title filters and retains the fixes for
archived files dated before 1970.
It includes isolated PDF/DOCX processing and bounded media previews.

The installer creates a launcher and sets up WebView2 if needed. This initial
release is unsigned. A Linux desktop preview is also available; macOS source build instructions
are available now. You can also let your local AI agent handle setup.

**Ubuntu 24.04 x64 desktop preview:** [Download the Debian package](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.4/searchi_0.1.4_amd64.deb)
and install with `sudo apt install ./searchi_0.1.4_amd64.deb`.
[Checksums](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.4/LINUX-DESKTOP-SHA256SUMS-0.1.4.txt).
Startup was tested in WSL using CPU; native graphical interaction and other
distributions still need testing. [Compatibility and evidence](docs/LINUX-DESKTOP.md).

**Running a Linux server?** The optional
[Linux x64 headless preview](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.4/searchi-headless_0.1.0_linux-x86_64-014.tar.xz)
includes the CLI, read-only MCP server, Google runtime and media helpers.
It was tested on Ubuntu 24.04 and requires GLIBC 2.39 and a compatible C++
runtime. [Checksums](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.4/LINUX-SHA256SUMS-0.1.4.txt)
· [Headless setup](docs/LINUX-HEADLESS.md). No desktop dependencies are required.

### Install with your agent — copy and paste

Paste this into an agent that can run commands on your computer:

```text
Install searchi on this computer and get it ready for my first search.
Official repository: https://tea.karlcom.de/karl/searchi

Detect my operating system and processor architecture. Use a suitable official
release from the README or releases page, including the Windows installer or
compatible Ubuntu desktop package or Linux headless archive. Check its documented system requirements,
verifying its published checksums. Otherwise,
set up the current source version using the repository's installation/build
instructions. Handle the required tools and dependencies for me; don't just
give me a list of commands to run. Keep the installation in a dedicated folder
and preserve any existing searchi settings and index.

Install the desktop app by default. On headless Linux, install the command-line
version instead, without desktop dependencies. Set up the genuine local Google
EmbeddingGemma 2 runtime and model, and the media helpers available for my
platform. Use supported hardware acceleration with CPU fallback. Explain any
large downloads or platform limitations before proceeding with those steps.

Launch searchi and check that it actually opens and its local search model is
ready. Create a normal launcher or shortcut so I can open it again. If a prerequisite, platform component
or permission prevents setup, explain precisely what is missing; don't report
a working installation until it is verified. Ask for my help only when a
password, system approval or other manual action is required.

Let me choose which folders to index. Keep search local and optional cloud
summaries disabled. On desktop, show me how to add a folder; on headless Linux,
prepare the chosen folder through the CLI. Finish with a filename search
followed by a search in my own words.
```

Your agent needs internet access and permission to install software locally.
Windows x64 setup can use the published installer; Ubuntu 24.04 x64 can use the
desktop preview, and compatible headless Linux
systems can use the preview archive. Other platforms currently build from
source. The local search model downloads approximately **865 MB**
once. The Windows 0.1.6 speech feature automatically downloads about
**149 MB** of additional local assets afterward. Cached assets are reused;
filename and keyword search remain available while models prepare. Your agent should report any platform
limitation it encounters.

Prefer to set it up yourself? See the
[build and launch instructions](docs/BUILDING.md).

### Your first search

Once searchi is running:

1. Choose **Add folder**, browse to the folder you want to search, then choose
   **Index folder**.
2. Start with a filename or words you remember. These searches become
   available as files are indexed.
3. Let the local search model prepare in the background. First setup downloads
   approximately **865 MB** and needs an internet connection. Document and code
   search by meaning can begin once the smaller text model and text index are
   ready, while the larger media model continues downloading. The app shows
   progress and keeps text search available if media setup needs a retry.
4. Describe what you're looking for, select a result and inspect the preview.
   Press **Enter** to open the selected file in its usual application.

How quickly a folder becomes searchable depends on its size and contents.
The desktop keeps its search model warm for subsequent searches.
searchi watches your chosen folders and updates search in the background as
files change. You can also use **Reindex** to check a folder again, for example
after reconnecting an external drive.

searchi automatically chooses supported graphics acceleration when available
and falls back to CPU when it cannot use it. You do not need a graphics
development toolkit. Hardware and release validation are still in progress.

## Private by design

You choose the folders to index. By default, file contents, previews and search
processing stay local. Ordinary searches aren't sent to a cloud AI service.

If you enable optional AI answers, an explicit **Summarize** or **Ask** action
sends the previewed document excerpt to the endpoint you choose. Ordinary
searches continue to run locally.

The model download happens during setup. Once it's ready, semantic inference
runs on your device. The local search index contains information from your
files, so protect it as you would the files themselves.

## Documents and media

| Files | Current support |
| --- | --- |
| Documents | PDF, DOCX, plain text, Markdown and source code |
| Photos | JPEG, PNG, WebP and BMP |
| Music and audio | MP3, FLAC, WAV, M4A, OGG, Opus, AAC and AIFF |
| Movies and video | MP4, MKV, MOV, AVI, WebM, M4V and MPEG |

**Media search is experimental.** Image, audio and video search are implemented,
but relevance still needs improvement. Music descriptions can produce broad
matches; use exact artist/title filters when you know the tags. Video sampling
can miss a brief scene. In speech search, recognized text can
contain errors or miss words, and timestamps are estimates rather than verified
word positions. When your files contain no suitable match, semantic search may
still show the closest results; a returned result does not prove the requested
content exists. Inspect the passage or preview before relying on it.
Playback also depends on the formats your system supports; you can open a
file in its usual player if the preview cannot play it.

## Fast should feel fast

Each search shows a compact result count and timing summary. Want to look
closer? Enable **Performance details** in settings for a breakdown of where
the time went. Copied timing reports exclude your search text and file paths.

<details>
<summary>See the optional performance view</summary>

![searchi showing measured search timings in its optional performance panel](docs/screenshots/performance-details.png)

</details>

## Your agent can search, too

Connect a local AI agent to searchi's read-only **MCP server**. It can search
your chosen index and return snippets, source locations and search timings
using the same engine as the desktop. A reusable skill also helps agents use
searchi through the command line. [Connect an agent](docs/AGENT-INTEGRATION.md).
Your agent receives the returned excerpts; cloud agents handle them according
to that client's configuration.

On Windows x64, your agent can use the optional
[CLI/MCP download](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.6/searchi-cli-windows-0.1.6.zip)
with its [own checksum](https://tea.karlcom.de/karl/searchi/releases/download/v0.1.6/searchi-cli-windows-0.1.6.zip.sha256).
Extract the ZIP alongside the installed desktop runtime helpers; it includes
the document extraction helper. No Rust build is needed. Install the desktop app first for the model setup and
runtime helpers, then connect the CLI to that app's existing index.

## Optional answers, your choice

Want a short summary or an answer about a passage? Connect your preferred
**OpenAI-compatible endpoint**, including a local model server. Preview exactly
which excerpt will be sent, then choose **Summarize** or **Ask**. The feature is
off by default; search works without it. [Set up optional answers](docs/AI-ANSWERS.md).

## Help shape searchi

Found a problem, or searched for something that should have been easy to find?
[Report it or suggest an improvement](https://tea.karlcom.de/karl/searchi/issues).
Describe what you expected and what happened; use made-up examples if your
files contain private information.

For contributors: [building searchi and the headless Linux CLI](docs/BUILDING.md)
· [roadmap](docs/ROADMAP.md) · [search-quality evaluation](docs/MEDIA-QUALITY.md).

The screenshots show the working interface searching real example files with
the local Google model. They are browser captures of the app interface;
operating-system window borders are omitted. [Photo credits](fixtures/media/README.md).

Made by Karl. Open source under the [MIT license](LICENSE).