istok

istok index, search and graph

Inspect and rebuild the local code index, search repository content, and explore symbols and their relationships.

Istok keeps a local index of each project’s repository. Agents use it through MCP to retrieve relevant code, and every claim includes code retrieved from it. These commands expose the same index for inspection and troubleshooting. You normally do not need to manage it.

Commands

istok index status
istok index rebuild

istok search QUERY [--limit N]

istok graph symbol NAME [--limit N]
istok graph neighbors NAME [--kind KIND] [--limit N]
istok graph path FROM TO [--max-depth N] [--limit N]

All commands work on the project that contains the current directory and accept --json and --database PATH.

Automatic freshness

Istok checks whether the index is up to date whenever it is used:

  • when you run istok search or a graph read;
  • when an agent claims a task and Istok prepares code context for the run.

If the repository changed, Istok refreshes the index first. A stale index is never used as if it were current: if no usable index can be prepared, search fails and a normal claim does not create a run, rather than returning outdated results.

istok init builds the first index. A project registered through MCP gets its first index the first time retrieval is needed. There is no index update step.

What gets indexed

In a Git repository, Istok indexes tracked files and untracked files that Git does not ignore. It respects nested .gitignore files and .git/info/exclude. Outside a Git worktree, it walks the filesystem with Git-style ignore matching.

Add Istok-only exclusions in a .istokignore file in the repository. It only adds exclusions; it cannot re-include files Git ignores.

Istok always skips:

  • .env and .env.* files;
  • binary files and files that are not valid UTF-8 text;
  • files larger than 512 KiB;
  • dependency caches, build outputs, and hidden version-control directories.

Files with an unknown extension are indexed as plain text if they pass these checks.

index status

istok index status

Shows the current index and its health without refreshing or rebuilding anything. Start here when search or claims fail.

index rebuild

istok index rebuild

Forces a new index build. This is a repair and diagnostic tool, not a step before normal work. The new index generation becomes active only after it has been prepared successfully.

istok search "order not found"
istok search "order not found" --limit 20

Returns results ranked by relevance (10 by default), with the repository location, matched content, score, and provenance explaining why each result matched, for example an exact symbol name, identifier, path, or lexical match.

Use search when you know what text, identifier, or behaviour you are looking for.

graph

The code graph covers Go, TypeScript (including TSX), and JavaScript (including JSX). Files in other languages are still indexed for search. Use the graph when you know a symbol and want to see how it relates to other code.

Find a symbol

istok graph symbol OrderService
istok graph symbol orders.OrderService --limit 10

Accepts exact short names and qualified names. Returns up to 20 symbols by default.

Neighbors

istok graph neighbors OrderService
istok graph neighbors OrderService --kind calls --limit 20

--kind can be repeated; kinds are contains, imports, calls, references, inherits, and implements. Results include the relationship and where its evidence was found. Up to 20 neighbors by default.

Path between symbols

istok graph path OrderHandler OrderRepository
istok graph path OrderHandler OrderRepository --max-depth 6 --limit 10

Finds bounded paths between two symbols. Defaults: depth 6, 10 paths.

Degraded graph

If some files cannot contribute complete structural information, Istok keeps search available and reports the graph as degraded, rather than pretending it is complete. Check with istok index status; if the problem persists and you need the graph, run istok index rebuild.

JSON output

Search results use the retrieval payload istok.retrieval.v1 and graph results use istok.graph.v1, each inside the versioned Istok envelope. See JSON output.

Help

istok index --help
istok search --help
istok graph --help