istok

index, search and graph

Inspect the local repository index, search project code, and explore relationships between symbols.

Istok maintains a local repository index that coding agents can use to retrieve code relevant to their work.

The CLI exposes the same retrieval layer for direct inspection and troubleshooting through three command groups:

  • istok index inspects and repairs the repository index;
  • istok search performs ranked repository search;
  • istok graph explores symbols and relationships in the codebase.

For normal agent workflows, you usually do not need to manage the index yourself.

Commands

The retrieval-related CLI surface is:

istok index status
istok index rebuild

istok search QUERY

istok graph symbol NAME
istok graph neighbors NAME
istok graph path FROM TO

All commands operate on the Istok project associated with the current working directory.

Automatic freshness

Istok checks repository index freshness when the index is actually needed.

Freshness checks happen automatically when:

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

The first index is also prepared when a project is initialized.

You do not need an index update step before normal work.

Conceptually:

Repository changes
       ↓
search / graph / task claim
       ↓
freshness check
       ↓
refresh if needed
       ↓
read current index

What gets indexed

For Git repositories, Istok indexes tracked files together with untracked files that are not ignored by Git.

Repository discovery respects Git ignore rules, including nested .gitignore files and .git/info/exclude.

You can add Istok-specific exclusions with a .istokignore file in the repository:

.istokignore

.istokignore only adds exclusions. It does not re-include files that Git already ignores.

Istok also excludes files that should not participate in repository retrieval:

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

The default maximum indexed file size is 512 KiB.

Files with an unknown extension can still be indexed as plain text when they pass the content and size checks.

For directories outside a Git worktree, Istok uses filesystem discovery with Git-style ignore matching.

Inspect index status

Inspect the current index without modifying it:

istok index status

index status is an inspection command. It does not refresh or rebuild the index.

Use it when troubleshooting repository retrieval or when you want to inspect the current indexed state directly.

Rebuild the index

Force a new index build with:

istok index rebuild

A rebuild is primarily a repair and diagnostic operation.

Normal search, graph, and task-claim workflows maintain freshness automatically, so rebuilding before regular agent work is unnecessary.

Istok creates a new index generation and only makes it active after the rebuilt retrieval state has been successfully prepared.

Search the repository

Search indexed repository content with:

istok search "authentication timeout"

Limit the number of results:

istok search "authentication timeout" --limit 10

Search results are ranked according to their relevance to the query.

Results can include useful retrieval information such as:

  • repository location;
  • matched content;
  • score;
  • provenance explaining why the result matched.

For example, a result may be relevant because of an exact symbol name, identifier, path, or lexical match.

Search freshness

istok search checks index freshness before reading from it.

If the repository changed since the current index was produced, Istok refreshes the retrieval state first.

A stale index is not silently used as if it were current.

If no usable repository index can be prepared, the search fails instead of returning potentially misleading stale results.

Find a symbol

Find a symbol by name:

istok graph symbol AuthService

Limit the results:

istok graph symbol AuthService --limit 10

Symbol lookup supports exact short names and qualified names.

For example, depending on the repository, you might query:

AuthService

or a qualified symbol name:

auth.AuthService

Inspect symbol relationships

Inspect relationships around a symbol:

istok graph neighbors AuthService

Limit the output:

istok graph neighbors AuthService --limit 20

You can filter relationships by kind:

istok graph neighbors AuthService \
  --kind calls \
  --limit 20

--kind can be used to narrow the graph output to relationships relevant to the investigation.

Neighbor results preserve information about the relationship and where the evidence for that relationship was found.

Find a path between symbols

Search for a bounded path between two symbols:

istok graph path Handler Service

Limit traversal depth:

istok graph path Handler Service --max-depth 6

You can also limit the number of returned paths:

istok graph path Handler Service \
  --max-depth 6 \
  --limit 10

This is useful when investigating how two parts of a codebase are connected.

Search and graph serve different purposes

Use search when you know what concept, text, identifier, or behavior you are looking for:

istok search "refresh token"

Use graph when you know which symbol you want to understand and how it relates to other code:

istok graph symbol RefreshTokenService

istok graph neighbors RefreshTokenService

Together they provide two views of the repository:

Repository
   │
   ├── search
   │     ↓
   │   relevant code and text
   │
   └── graph
         ↓
       symbols and relationships

Degraded graph results

Repository files are not always equally suitable for structural analysis.

If some source cannot contribute complete graph information, Istok can still keep repository search available while reporting the structural retrieval state as degraded.

This lets lexical retrieval continue without pretending that graph information is complete.

Use:

istok index status

when you need to inspect retrieval health directly.

Retrieval during task claim

Agents do not normally need to issue search and graph commands manually before starting work.

When an agent claims a task, Istok prepares repository retrieval as part of the claim workflow and stores the selected context with the run.

Conceptually:

Task
  ↓
claim
  ↓
refresh repository index
  ↓
retrieve relevant code
  ↓
Context snapshot
  ↓
Run

If repository retrieval cannot be prepared, the normal claim does not create a run with silently stale code context.

This keeps the context attached to an attempt consistent with the repository state available when the run began.

JSON output

Retrieval commands support structured output where available:

istok search "authentication" --json

Retrieval JSON uses a versioned payload so scripts and integrations can identify the contract they receive.

Graph results use their own versioned graph payload.

See JSON output for the general output conventions.

Command help

Use built-in help for the exact options supported by your installed version:

istok index --help
istok index status --help
istok index rebuild --help

istok search --help

istok graph --help
istok graph symbol --help
istok graph neighbors --help
istok graph path --help

Next

Continue with MCP for the agent-facing interface to Istok.