Docs

Install

One installer. The small bootstrap executable from the releases page installs the shared CLI/engine, MCP and agent skill, verifies both models, and includes desktop by default. Windows and Linux on x86-64 and macOS on Apple silicon and Intel are supported.

Agent installation. These scripts download and verify the same binary installer. No Rust or Node is needed. They add ixos to your user PATH and verify the models from Hugging Face.

For CLI/MCP/skill only, append -NoDesktop on Windows, or use sh -s -- --no-desktop after the pipe on macOS/Linux. Open a new terminal after installation. Published engine and desktop releases are required for these links.

ixos update updates the CLI/MCP/skill; ixos update --desktop includes desktop. CLI and MCP suggest available updates, while desktop applies compatible engine and signed app updates on launch/login and restarts. Custom engine overrides are preserved.

After setup, everything works offline. Keyword search, grep and read never need a model. To install without a network, see setup and model.

First search

From a project folder, ask for something by what it does. This example shows results from Ixos's source:

Each result is the file and the passage that matched best, with line numbers:

ixos-core/src/cloud.rs:184:/// Check if we should skip processing this file to avoid triggering a cloud download
ixos-core/src/cloud.rs:185:///
ixos-core/src/cloud.rs:186:/// Returns `true` if the file should be skipped (cloud-only)
ixos-core/src/discover.rs:5:/// `build` is intentionally absent: it can be a source module (e.g. Clap).
…

Add --json for output a program can read:

{"results":[{"path":"ixos-core/src/cloud.rs","score":0.73457474,"snippet":{
  "path":"ixos-core/src/cloud.rs","start_line":182,"end_line":186,"text":"…"}}]}

How Ixos ranks

Every search runs two rankings and averages them.

Scores order the results; they are not probabilities. A query that is an exact identifier only matches files that contain it. Choose a mode with --mode:

The two profiles use different models:

Quick search

Press Ctrl Space anywhere to open the quick search over whatever you are working in. Keyword results appear as you type; meaning is added a moment later and the list re-orders. The selected result shows its best passage beside the list. The shortcut can be changed in Settings.

The app lives in the tray. Closing a window hides it, so the next search starts warm, unless you turn off Keep running when closed.

Search window

The main window shows the full list on the left and the file on the right, scrolled to the passage, with your query highlighted. Three menus sit in the search bar:

Settings

Shortcuts

search

Finds files by what they are about, by keywords, or both.

Defaults for profile, limit and context come from the settings file.

grep

Finds exact text or a regular expression. It follows the same ignore rules as search and needs no model.

read

Prints lines from a file. PDFs and Office files are read as their extracted text, so line numbers refer to that text rather than pages.

cache

Shows or removes the records Ixos keeps. Removing them is safe; Ixos rebuilds them on the next search. Only Ixos metadata is touched, never the files themselves.

config

Shows the shared settings, or changes one. The desktop app reads the same file.

The keys are listed under settings file.

setup and model

ixos setup downloads both models from pinned Hugging Face revisions, checks their SHA-256 hashes and installs the agent skill. A failed download leaves nothing half installed; run it again once you are online.

Without a network, copy the three files of each model from ixos-code and ixos-documents into a folder, then install from it:

If you skip setup, the first search that needs meaning downloads the model it needs.

doctor

Loads the model, checks that the cache can be written, and runs a small search.

Claude Code and Codex

ixos mcp starts an MCP server over stdio that gives an agent three tools: search, grep and read. Register it once per project, with the project's full path:

Other MCP clients take the same command in their settings file:

If ixos is not on your path, use its full path. Quote Windows paths that contain spaces. Reload the agent afterwards and check the tools with a real call. ixos setup also installs a short skill for Claude Code and Codex that explains when each tool helps; it does not register the server.

Tools

Only query, pattern or path (or requests) is required; the rest default to the server's folder and settings. Line ranges are inclusive. view is json by default; numbered returns compact source with line numbers and groups grep hits by file.

within reads a whole function by name, including its doc comment. Owner::name picks a method. Add "body": true to start at the body. If the name is defined more than once, the answer lists each definition instead of guessing.

Function evidence

For code, search can return the functions in each top file that best match the query, next to the usual passage. File ranking does not change.

With evidence on, matches replaces snippet; its first entry is the usual passage. Each match has lines, text, and when known a symbol with the definition's extent. Evidence applies to the code profile with a model; keyword search and documents return their normal passage.

Batched reads

read accepts up to eight ranges in one call through requests. Each can carry an id, and results come back in the same order.

The byte budget is split equally between the requests. A request that fails returns its own error and the others still run. dir, view and max_bytes apply to the whole call.

Source hashes

Search and read return a source_hash for each file. Pass it back as expected_source_hash and the read is refused if the file changed since, so an agent never acts on old line numbers.

When a read is cut short, continue from next_start_line. For one very long line, set characters and move character_offset forward using next_character_offset.

Settings file

The command, the agent server and the desktop app share one file, ixos/settings.toml, in your system's configuration folder.

Pass --config path/to/settings.toml to any command to use another file.

Environment variables

Records and cache

With Remember files on, Ixos saves one small record in each file's own metadata: an alternate data stream named :ixos on Windows and the extended attribute user.ixos on macOS and Linux. Where a drive cannot hold metadata, the record goes in one database in the application cache instead. The file's contents and modified time are never changed.

A record stays valid while the file and the model are the same. Change the file and only that file is read again.

Output and size limits

Ixos reads text, PDF and Office files. Scanned pages without a text layer are skipped, as are symbolic links, files your ignore rules exclude, and cloud files that have not been downloaded.

Retrieval benchmarks

Two public sets: 260 descriptions of functions from 26 repository families in RepoQA, and all 300 test claims in SciFact over 5,183 papers. Every method returns 10 files with 2 lines of context under the same 6,000-byte limit.

These sets were also looked at during development, so read them as a check rather than a fresh test. RepoQA descriptions are generated, and neither set measures PDF extraction or whether an agent finishes its task. Per-query results and the commands to reproduce them are in the repository.

Speed

260 searches through the agent server, one per RepoQA description, on a Ryzen 7 5800X with the folders already read once.

The first search in a new folder reads every file. One check on 9,892 files (65 MB) took 2,873 ms from a fresh process, including loading the model, and 573 ms for the second search in a running server.

Agent studies

On the RepoQA set, Ixos put the right file in the top ten for 240 of 260 descriptions. The passage it showed overlapped the function being described for 101 of them; with function evidence on, 171 did.

That makes the right code easier to reach. It is not the same as an agent doing better work: in controlled runs, agents using Ixos were not reliably more correct and did not reliably use less context than agents using ordinary tools. The full write-up has the details.