ish — Interactive Semantic Hunt

Semantic search for code, inspired by fzf. Point ish at a directory. It parses each source file into named chunks, embeds them with a local model, and ranks them against your query. Everything runs on your machine.

Languages: Python, C and C++, Markdown, and AsciiDoc. Documentation is indexed beside the code it describes, so one query searches both.

Install

pip install interactive-semantic-hunt

Nothing in that install compiles: the default backend reaches Ollama over HTTP with the standard library. A backend that runs the model in this process is an extra — [llama] for llama.cpp, [st] for sentence-transformers.

To work on ish itself, clone it and run uv sync.

The default embedding backend is Ollama, which keeps the model resident so no run pays a model load. Start it once and pull the embedding model:

ollama serve
ollama pull nomic-embed-text

Set OLLAMA_HOST to reach a daemon elsewhere.

Two other backends need no daemon:

• --embedder llama.cpp downloads a GGUF model and loads it per run. Slower per query, faster for a first index of a large tree. Needs the [llama] extra.
• --embedder st uses sentence-transformers. Needs the [st] extra.

Use

List every chunk under a path:

ish src/

src/ish/domain/chunk.py:7-28  class  Chunk

Search for a query:

ish "parse a python file" src/

[0.71] src/ish/adapters/parser/python.py:14-31  method  PythonParser.parse

Run the interactive picker and open the selection in your editor. Type to search, up/down or ctrl+p/ctrl+n to move, enter to choose, escape to quit. Narrow without leaving the query line:

state machine transitions              every language
lang:cpp state machine transitions     the implementation
lang:yaml under:/10.System/ state      the tests that cover it
type:doc how do I configure this       the prose, not the code
type:test,doc retry backoff            the tests and what they document

Press Tab to finish a filter word. ty becomes type:, lang:cp becomes lang:cpp, and under:/s becomes under:/src/; a word with several answers grows as far as they agree and names the rest. ish-complete does the work, so any picker can call it.

lang:, under:, and type: work in the query line of every interface — the command line, the picker, Neovim, and MCP. The words are taken out before the query is embedded, so the model sees the question rather than how it was narrowed.

A language may be named however it comes to mind. c, c++, cxx, h, and hpp all mean cpp, because one parser reads them all; adoc means asciidoc, md means markdown, py means python, and yml means yaml.

type: sorts every chunk into exactly one kind. A path decides before a language does, so a YAML fixture counts as a test rather than as config:

A repository that names its trees its own way can say so, in .ish/config.toml:

type_patterns = [
  "test:/[0-9.]*(Tests|Verification)/",
  "doc:/[0-9.]*Specification/",
]

The first match wins; anything unmatched keeps the reading above.

A config beside a subtree adds to the one above it, so a tree settles only what it names and inherits the rest. Searching inside an already-indexed tree reads that tree's index and narrows the answers to the path, rather than starting a second index of the same files.

nvim $(ish -i src/)

Options

Logs go to stderr, so you can pipe stdout safely. A file that cannot be read or parsed is counted in one line; -v names them.

Use from Neovim

contrib/nvim/ish.lua is an fzf-lua picker. Copy it to lua/utils/ish.lua and bind it:

map('n', '<leader>fi', function() require('utils.ish').search() end,
    { desc = 'Semantic search (ish)' })

It reads --format grep, so the built-in previewer opens each result at its line, and prints the rank in the leftmost column. search_lang({'cpp'}), search_type({'doc'}), and search_here() narrow it, as does a lang:, type:, or under: word typed into the query.

While the index refreshes, require('utils.ish').statusline() renders a bar for a statusline — ish ███░░░░░ 38% — and an empty string when idle. It reads vim.g.ish_index_status, which the picker keeps up to date, and shows ish ✓ briefly when a refresh finishes. Nothing is reported through vim.notify: with cmdheight = 0 there is no command line to put a message in, so nvim draws one over the last screen row — the statusline itself.

The picker never blocks the editor: results are written as they arrive, so typing stays smooth however long a search takes.

contrib/nvim/ish_server.lua keeps one ish-mcp process per session. It starts on the first search and is reused after that, which cuts a keystroke from about 500 ms to about 150 ms. Copy it beside the picker.

Use from Python

from ish.interfaces.python.api import Ish

with Ish("src/") as ish:
    for chunk, score in ish.search("type:doc how to configure", limit=5):
        print(score, chunk.path, chunk.symbol)
    print(ish.status())

Ish holds the index open, so a second query costs a search rather than a process start. It offers search(), chunks(), index(), refresh_all(), and status(), and reads lang:, type:, and under: out of the query exactly as the other interfaces do.

Use from an agent

ish-mcp serves the same search over the Model Context Protocol, so an agent can query the index directly. Add it to a project with .mcp.json:

{
  "mcpServers": {
    "ish": { "command": "uv", "args": ["run", "ish-mcp"] }
  }
}

It offers search_code, list_chunks, index_status, and refresh_index. The server stays resident, so a query costs about 58 ms rather than a process start.

A call may narrow one search with lang, under, type, and limit, or write the same filters into the query text. It cannot change what is indexed — those settings come from ish.toml only, so no single call can shrink an index that another call depends on.

Index

The index persists in SQLite under $XDG_DATA_HOME/ish/, one file per scanned tree. A search of a parent reads the indexes below it and refreshes none — choosing one of them to write to would be wrong — so it warns and offers --refresh, which visits each tree in turn. A repeated query reuses it, so only changed files are parsed and only new text is embedded. A renamed file re-embeds nothing.

Each index records the tree it was built from, so searching a directory also searches every index below it. Index the parts of a large project separately and search the whole from its root:

ish "warm" project/docs        # index one part
ish "warm" project/firmware    # and another
ish "how is exposure set" project    # searches both

Searching a parent never rewrites an index below it. Pass --no-federate to use only the index of the exact path.

The index records where each chunk is — its path, line range, kind, and name — together with the embedding vector. It does not store the source, so it is not a second readable copy of your code. Previews are read from the file, which also means they always show the current content.

Configure

Every command-line option is also a key in ish.toml, under the same name. Put project settings in ish.toml at the root of your repository:

embedder = "ollama"
model = "mxbai-embed-large"
limit = 10
ignore = [".git", ".venv", "build", "node_modules"]

# Regular expressions, searched against the path.
exclude = ["/vendor/", "_pb2\\.py$", "(_test|_spec)\\.py$"]

include and exclude take regular expressions rather than globs, so /vendor/ matches at any depth and alternation works. exclude wins over include.

--git is on by default, so anything a .gitignore covers stays out of the index. Pass --no-git to index it anyway.

--lang and --under narrow what a search returns. They never change what is indexed, so a narrowed query cannot shrink the index:

ish "how is ranking done" --lang python
ish "installation steps" --lang markdown asciidoc
ish "parse a header" --under '/include/'

User-level defaults go in ~/.config/ish/ish.toml. Later sources win:

defaults < ~/.config/ish/ish.toml < ./ish.toml < ISH_* environment < command line

Set any option from the environment with the ISH_ prefix, for example ISH_LIMIT=20 or ISH_IGNORE=build,dist.

Develop

uv run poe check   # lint, typecheck, test

The architecture is ports and adapters. spec.md holds the requirements, and .claude/CLAUDE.md describes the layers and the composition root.